Modified: maven/website/content/guides/mini/guide-mirror-settings.html ============================================================================== --- maven/website/content/guides/mini/guide-mirror-settings.html (original) +++ maven/website/content/guides/mini/guide-mirror-settings.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-mirror-settings.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-mirror-settings.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,9 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Jason van Zyl, Brian Fox, Robert Scholte" /> + <meta name="author" content="Jason van Zyl +Brian Fox +Robert Scholte" /> <meta name="date" content="2015-01-02" /> <title>Maven – Guide to Mirror Settings</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +50,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Mirror Settings <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-mirror-settings.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Mirror Settings <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-mirror-settings.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -152,40 +154,16 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Using Mirrors for Repositories</h2> -<p>With <a href="/guides/introduction/introduction-to-repositories.html">Repositories</a> you specify from which locations you want to <em>download</em> certain artifacts, such as dependencies and maven-plugins. Repositories can be <a href="../mini/guide-multiple-repositories.html">declared inside a project</a>, which means that if you have your own custom repositories, those sharing your project easily get the right settings out of the box. However, you may want to use an alternative mirror for a particular repository without changing the project files.</p> +<section> +<h1>Using Mirrors for Repositories</h1> +<p>With <a href="/guides/introduction/introduction-to-repositories.html">Repositories</a> you specify from which locations you want to <i>download</i> certain artifacts, such as dependencies and maven-plugins. Repositories can be <a href="../mini/guide-multiple-repositories.html">declared inside a project</a>, which means that if you have your own custom repositories, those sharing your project easily get the right settings out of the box. However, you may want to use an alternative mirror for a particular repository without changing the project files.</p> <p>Some reasons to use a mirror are:</p> <ul> - -<li> -<p>There is a synchronized mirror on the internet that is geographically closer and faster</p></li> -<li> -<p>You want to replace a particular repository with your own internal repository which you have greater control over</p></li> -<li> -<p>You want to run a <a href="../../repository-management.html">repository manager</a> to provide a local cache to a mirror and need to use its URL instead</p></li> -</ul> +<li>There is a synchronized mirror on the internet that is geographically closer and faster</li> +<li>You want to replace a particular repository with your own internal repository which you have greater control over</li> +<li>You want to run a <a href="../../repository-management.html">repository manager</a> to provide a local cache to a mirror and need to use its URL instead</li></ul> <p>To configure a mirror of a given repository, you provide it in your settings file (<code>${user.home}/.m2/settings.xml</code>), giving the new repository its own <code>id</code> and <code>url</code>, and specify the <code>mirrorOf</code> setting that is the ID of the repository you are using a mirror of. For example, the ID of the main Maven Central repository included by default is <code>central</code>, so to use the different mirror instance, you would configure the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><settings> +<div class="source"><pre class="prettyprint linenums"><settings> ... <mirrors> <mirror> @@ -196,18 +174,16 @@ under the License. </mirror> </mirrors> ... -</settings> -</code></pre></div> +</settings></pre></div> <p>Note that there can be at most one mirror for a given repository. In other words, you cannot map a single repository to a group of mirrors that all define the same <code><mirrorOf></code> value. Maven will not aggregate the mirrors but simply picks the first match. If you want to provide a combined view of several repositories, use a <a href="../../repository-management.html">repository manager</a> instead.</p> <p>The settings descriptor documentation can be found on the <a href="../../maven-settings/settings.html">Maven Local Settings Model Website</a>.</p> -<p><strong>Note</strong>: The official Maven repository is at <code>https://repo.maven.apache.org/maven2</code> hosted by the Sonatype Company and is distributed worldwide via CDN.</p> -<p>A list of known mirrors is available in the <a href="https://repo.maven.apache.org/maven2/.meta/repository-metadata.xml"; class="externalLink">Repository Metadata</a>. These mirrors may not have the same contents and we don't support them in any way.</p></section><section> -<h2>Using A Single Repository</h2> +<p><b>Note</b>: The official Maven repository is at <code>https://repo.maven.apache.org/maven2</code> hosted by the Sonatype Company and is distributed worldwide via CDN.</p> +<p>A list of known mirrors is available in the <a class="externalLink" href="https://repo.maven.apache.org/maven2/.meta/repository-metadata.xml";>Repository Metadata</a>. These mirrors may not have the same contents and we don't support them in any way.</p></section><section> +<h1>Using A Single Repository</h1> <p>You can force Maven to use a single repository by having it mirror all repository requests. The repository must contain all of the desired artifacts, or be able to proxy the requests to other repositories. This setting is most useful when using an internal company repository with a <a href="../../repository-management.html">Maven Repository Manager</a> to proxy external requests.</p> -<p>To achieve this, set <code>mirrorOf</code> to <code>\*</code>.</p> -<p><strong>Note:</strong> This feature is only available in Maven 2.0.5+.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><settings> +<p>To achieve this, set <code>mirrorOf</code> to <code>*</code>.</p> +<p><b>Note:</b> This feature is only available in Maven 2.0.5+.</p> +<div class="source"><pre class="prettyprint linenums"><settings> ... <mirrors> <mirror> @@ -218,41 +194,26 @@ under the License. </mirror> </mirrors> ... -</settings> -</code></pre></div></section><section> -<h2>Advanced Mirror Specification</h2> +</settings></pre></div></section><section> +<h1>Advanced Mirror Specification</h1> <p>A single mirror can handle multiple repositories. This is typically used in conjunction with a repository manager, that gives easy centralised configuration of the list of repositories behind.</p> <p>The syntax:</p> <ul> - -<li> -<p><code>\*</code> matches all repo ids.</p></li> -<li> -<p><code>external:\*</code> matches all repositories except those using localhost or file based repositories. This is used when you want to exclude redirecting repositories that are defined for Integration Testing.</p></li> -<li> -<p>since Maven 3.8.0, <code>external:http:\*</code> matches all repositories using HTTP except those using localhost.</p></li> -<li> -<p>multiple repositories may be specified using a comma as the delimiter</p></li> -<li> -<p>an exclamation mark may be used in conjunction with one of the above wildcards to exclude a repository id</p></li> -</ul> +<li><code>*</code> matches all repo ids.</li> +<li><code>external:*</code> matches all repositories except those using localhost or file based repositories. This is used when you want to exclude redirecting repositories that are defined for Integration Testing.</li> +<li>since Maven 3.8.0, <code>external:http:*</code> matches all repositories using HTTP except those using localhost.</li> +<li>multiple repositories may be specified using a comma as the delimiter</li> +<li>an exclamation mark may be used in conjunction with one of the above wildcards to exclude a repository id</li></ul> <p>Be careful not to include extra whitespace around identifiers or wildcards in comma separated lists. For example, a mirror with <code><mirrorOf</code>> set to <code>!repo1, *</code> will not mirror anything while <code>!repo1,*</code> will mirror everything but <code>repo1</code>.</p> <p>The position of wildcards within a comma separated list of repository identifiers is not important as the wildcards defer to further processing and explicit includes or excludes stop the processing, overruling any wildcard match.</p> <p>When you use the advanced syntax and configure multiple mirrors, the declaration order matters. When Maven looks for a mirror of some repository, it first checks for a mirror whose <code><mirrorOf></code> exactly matches the repository identifier. If no direct match is found, Maven picks the first mirror declaration that matches according to the rules above (if any). Hence, you may influence match order by changing the order of the definitions in the <code>settings.xml</code></p> <p>Examples:</p> <ul> - -<li> -<p><code>*</code> = everything</p></li> -<li> -<p><code>external:*</code> = everything not on the localhost and not file based.</p></li> -<li> -<p><code>repo,repo1</code> = repo or repo1</p></li> -<li> -<p><code>*,!repo1</code> = everything except repo1</p></li> -</ul> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><settings> +<li><code>*</code> = everything</li> +<li><code>external:*</code> = everything not on the localhost and not file based.</li> +<li><code>repo,repo1</code> = repo or repo1</li> +<li><code>*,!repo1</code> = everything except repo1</li></ul> +<div class="source"><pre class="prettyprint linenums"><settings> ... <mirrors> <mirror> @@ -269,10 +230,9 @@ under the License. </mirror> </mirrors> ... -</settings> -</code></pre></div></section><section> -<h2>Creating Your Own Mirror</h2> -<p>The size of the central repository is <a href="https://search.maven.org/stats"; class="externalLink">increasing steadily</a> To save us bandwidth and you time, mirroring the entire central repository is not allowed. (Doing so will get you automatically banned.) Instead, we suggest you setup a <a href="../../repository-management.html">repository manager</a> as a proxy.</p></section></section> +</settings></pre></div></section><section> +<h1>Creating Your Own Mirror</h1> +<p>The size of the central repository is <a class="externalLink" href="https://search.maven.org/stats";>increasing steadily</a> To save us bandwidth and you time, mirroring the entire central repository is not allowed. (Doing so will get you automatically banned.) Instead, we suggest you setup a <a href="../../repository-management.html">repository manager</a> as a proxy.</p></section> </main> </div> </div>
Modified: maven/website/content/guides/mini/guide-multiple-modules.html ============================================================================== --- maven/website/content/guides/mini/guide-multiple-modules.html (original) +++ maven/website/content/guides/mini/guide-multiple-modules.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-multiple-modules.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-multiple-modules.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,8 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Brett Porter, Karl Heinz Marbaise" /> + <meta name="author" content="Brett Porter +Karl Heinz Marbaise" /> <meta name="date" content="2015-03-13" /> <title>Maven – Guide to Working with Multiple Modules</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +49,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Working with Multiple Modules <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-multiple-modules.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Working with Multiple Modules <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-multiple-modules.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -154,80 +155,40 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to Working with Multiple Modules</h2> -<p>(If you're working with Maven 4, please refer to the <a href="./guide-multiple-modules-4.html">Maven 4 edition of this guide</a>)</p> +<section> +<h1>Guide to Working with Multiple Modules</h1> +<p>(If you're working with Maven 4, please refer to the <a href="./guide-multiple-modules-4.html"> Maven 4 edition of this guide</a>)</p> <p>As seen in the introduction to the POM, Maven supports project aggregation in addition to project inheritance. This section outlines how Maven processes projects with multiple modules, and how you can work with them more effectively.</p><section> -<h3>The Reactor</h3> -<p>The mechanism in Maven that handles multi-module projects is referred to as the <em>reactor</em>. This part of the Maven core does the following:</p> +<h2>The Reactor</h2> +<p>The mechanism in Maven that handles multi-module projects is referred to as the <i>reactor</i>. This part of the Maven core does the following:</p> <ul> - -<li> -<p>Collects all the available modules to build</p></li> -<li> -<p>Sorts the projects into the correct build order</p></li> -<li> -<p>Builds the selected projects in order</p></li> -</ul><section> -<h4>Reactor Sorting</h4> +<li>Collects all the available modules to build</li> +<li>Sorts the projects into the correct build order</li> +<li>Builds the selected projects in order</li></ul><section> +<h3>Reactor Sorting</h3> <p>Because modules within a multi-module build can depend on each other, it is important that the reactor sorts all the projects in a way that guarantees any project is built before it is required.</p> <p>The following relationships are honoured when sorting projects:</p> <ul> - -<li> -<p>a project dependency on another module in the build</p></li> -<li> -<p>a plugin declaration where the plugin is another module in the build</p></li> -<li> -<p>a plugin dependency on another module in the build</p></li> -<li> -<p>a build extension declaration on another module in the build</p></li> -<li> -<p>the order declared in the <code><modules></code> element (if no other rule applies)</p></li> -</ul> -<p>Note that only “instantiated” references are used - <code>dependencyManagement</code> and <code>pluginManagement</code> elements do not cause a change to the reactor sort order.</p></section><section> -<h4>Command Line Options</h4> +<li>a project dependency on another module in the build</li> +<li>a plugin declaration where the plugin is another module in the build</li> +<li>a plugin dependency on another module in the build</li> +<li>a build extension declaration on another module in the build</li> +<li>the order declared in the <code><modules></code> element (if no other rule applies)</li></ul> +<p>Note that only "instantiated" references are used - <code>dependencyManagement</code> and <code>pluginManagement</code> elements do not cause a change to the reactor sort order.</p></section><section> +<h3>Command Line Options</h3> <p>No special configuration is required to take advantage of the reactor, however it is possible to customize its behavior.</p> <p>The following command line switches are available:</p> <ul> - -<li> -<p><code>--resume-from</code> - resumes a reactor from the specified project (e.g. when it fails in the middle)</p></li> -<li> -<p><code>--also-make</code> - build the specified projects, and any of their dependencies in the reactor</p></li> -<li> -<p><code>--also-make-dependents</code> - build the specified projects, and any that depend on them</p></li> -<li> -<p><code>--fail-fast</code> - the default behavior - whenever a module build fails, stop the overall build immediately</p></li> -<li> -<p><code>--fail-at-end</code> - if a particular module build fails, continue the rest of the reactor and report all failed modules at the end instead</p></li> -<li> -<p><code>--non-recursive</code> - do not use a reactor build, even if the current project declares modules and just build the project in the current directory</p></li> -</ul> +<li><code>--resume-from</code> - resumes a reactor from the specified project (e.g. when it fails in the middle)</li> +<li><code>--also-make</code> - build the specified projects, and any of their dependencies in the reactor</li> +<li><code>--also-make-dependents</code> - build the specified projects, and any that depend on them</li> +<li><code>--fail-fast</code> - the default behavior - whenever a module build fails, stop the overall build immediately</li> +<li><code>--fail-at-end</code> - if a particular module build fails, continue the rest of the reactor and report all failed modules at the end instead</li> +<li><code>--non-recursive</code> - do not use a reactor build, even if the current project declares modules and just build the project in the current directory</li></ul> <p>Refer to the Maven command line interface reference for more information on these switches.</p></section></section><section> -<h3>More information</h3> +<h2>More information</h2> <ul> - -<li><a href="http://books.sonatype.com/mvnex-book/reference/multimodule.html"; class="externalLink">Chapter 6. A Multi-module Project (Maven by Example)</a></li> -</ul></section></section></section> +<li><a class="externalLink" href="http://books.sonatype.com/mvnex-book/reference/multimodule.html";> Chapter 6. A Multi-module Project (Maven by Example)</a></li></ul></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-multiple-repositories.html ============================================================================== --- maven/website/content/guides/mini/guide-multiple-repositories.html (original) +++ maven/website/content/guides/mini/guide-multiple-repositories.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-multiple-repositories.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-multiple-repositories.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to using Multiple Repositories <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-multiple-repositories.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to using Multiple Repositories <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-multiple-repositories.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -152,29 +152,10 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Setting up Multiple Repositories</h2> +<section> +<h1>Setting up Multiple Repositories</h1> <p>There are two different ways that you can specify the use of multiple repositories. The first way is to specify in a POM which repositories you want to use. That is supported both inside and outside of build profiles:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<div class="source"><pre class="prettyprint linenums"> <project> ... <repositories> @@ -191,12 +172,10 @@ under the License. </repositories> ... </project> - -</code></pre></div> -<p><strong>NOTE:</strong> You will also get the standard set of repositories as defined in the <a href="../introduction/introduction-to-the-pom.html#Super_POM">Super POM</a>.</p> +</pre></div> +<p><b>NOTE:</b> You will also get the standard set of repositories as defined in the <a href="../introduction/introduction-to-the-pom.html#Super_POM">Super POM</a>.</p> <p>The other way you can specify multiple repositories is by creating a profile in the <code>${user.home}/.m2/settings.xml</code> or <code>${maven.home}/conf/settings.xml</code> file like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<div class="source"><pre class="prettyprint linenums"> <settings> ... <profiles> @@ -219,30 +198,31 @@ under the License. </activeProfiles> ... </settings> - -</code></pre></div> +</pre></div> <p>If you specify repositories in profiles you must remember to activate that particular profile! As you can see above we do this by registering a profile to be active in the <code>activeProfiles</code> element.</p> <p>You could also activate this profile on the command like by executing the following command:</p> - -<div class="source"><pre class="prettyprint linenums"><code> +<div> +<pre> mvn -Pmyprofile ... - -</code></pre></div> +</pre></div> <p>In fact the <code>-P</code> option will take a CSV list of profiles to activate if you wish to activate multiple profiles simultaneously.</p> -<p><strong>Note</strong>: The settings descriptor documentation can be found on the <a href="../../maven-settings/settings.html">Maven Local Settings Model Website</a>.</p><section> -<h3>Repository Order</h3> +<p><b>Note</b>: The settings descriptor documentation can be found on the <a href="../../maven-settings/settings.html">Maven Local Settings Model Website</a>.</p><section> +<h2>Repository Order</h2> <p>Remote repository URLs are queried in the following order for artifacts until one returns a valid result:</p> -<p>1 effective settings:</p> -<p>A Global <code>settings.xml</code></p> -<p>A User <code>settings.xml</code></p> -<p>1 local effective build POM:</p> -<p>A Local <code>pom.xml</code></p> -<p>A Parent POMs, recursively</p> -<p>A Super POM</p> -<p>1 effective POMs from dependency path to the artifact.</p> +<ol style="list-style-type: decimal"> +<li>effective settings: +<ol style="list-style-type: upper-alpha"> +<li>Global <code>settings.xml</code></li> +<li>User <code>settings.xml</code></li></ol></li> +<li>local effective build POM: +<ol style="list-style-type: upper-alpha"> +<li>Local <code>pom.xml</code></li> +<li>Parent POMs, recursively</li> +<li>Super POM</li></ol></li> +<li>effective POMs from dependency path to the artifact.</li></ol> <p>For each of these locations, the repositories within the profiles are queried first in the order outlined at <a href="../introduction/introduction-to-profiles.html">Introduction to build profiles</a>.</p> <p>Before downloading from a repository, <a href="./guide-mirror-settings.html">mirrors configuration</a> is applied.</p> -<p>Effective settings and local build POM, with profile taken into account, can easily be reviewed to see their repositories order with <code>mvn help:effective-settings</code> and <code>mvn help:effective-pom -Dverbose</code>.</p></section></section></section> +<p>Effective settings and local build POM, with profile taken into account, can easily be reviewed to see their repositories order with <code>mvn help:effective-settings</code> and <code>mvn help:effective-pom -Dverbose</code>.</p></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-naming-conventions.html ============================================================================== --- maven/website/content/guides/mini/guide-naming-conventions.html (original) +++ maven/website/content/guides/mini/guide-naming-conventions.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-naming-conventions.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-naming-conventions.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Naming Conventions <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-naming-conventions.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Naming Conventions <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-naming-conventions.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -145,41 +145,18 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to naming conventions on groupId, artifactId, and version</h2> +<section> +<h1>Guide to naming conventions on groupId, artifactId, and version</h1> <ul> - -<li> -<p><strong>groupId</strong> uniquely identifies your project across all projects. A group ID should follow <a href="https://docs.oracle.com/javase/specs/jls/se6/html/packages.html#7.7"; class="externalLink">Java's package name rules</a>. This means it starts with a reversed domain name you control. For example,</p> +<li><b>groupId</b> uniquely identifies your project across all projects. A group ID should follow <a class="externalLink" href="https://docs.oracle.com/javase/specs/jls/se6/html/packages.html#7.7";>Java's package name rules</a>. This means it starts with a reversed domain name you control. For example, <p><code>org.apache.maven</code>, <code>org.apache.commons</code></p> <p>Maven does not enforce this rule. There are many legacy projects that do not follow this convention and instead use single word group IDs. However, it will be difficult to get a new single word group ID approved for inclusion in the Maven Central repository.</p> <p>You can create as many subgroups as you want. A good way to determine the granularity of the <code>groupId</code> is to use the project structure. That is, if the current project is a multiple module project, it should append a new identifier to the parent's <code>groupId</code>. For example,</p> <p><code>org.apache.maven</code>, <code>org.apache.maven.plugins</code>, <code>org.apache.maven.reporting</code></p></li> -<li> -<p><strong>artifactId</strong> is the name of the jar without version. If you created it, then you can choose whatever name you want with lowercase letters and no strange symbols. If it's a third party jar, you have to take the name of the jar as it's distributed.</p> +<li><b>artifactId</b> is the name of the jar without version. If you created it, then you can choose whatever name you want with lowercase letters and no strange symbols. If it's a third party jar, you have to take the name of the jar as it's distributed. <p>eg. <code>maven</code>, <code>commons-math</code></p></li> -<li> -<p><strong>version</strong> if you distribute it, then you can choose any typical version with numbers and dots (1.0, 1.1, 1.0.1, …). Don't use dates as they are usually associated with SNAPSHOT (nightly) builds. If it's a third party artifact, you have to use their version number whatever it is, and as strange as it can look. For example,</p> -<p><code>2.0</code>, <code>2.0.1</code>, <code>1.3.1</code></p></li> -</ul></section></section> +<li><b>version</b> if you distribute it, then you can choose any typical version with numbers and dots (1.0, 1.1, 1.0.1, ...). Don't use dates as they are usually associated with SNAPSHOT (nightly) builds. If it's a third party artifact, you have to use their version number whatever it is, and as strange as it can look. For example, +<p><code>2.0</code>, <code>2.0.1</code>, <code>1.3.1</code></p></li></ul></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-new-committers.html ============================================================================== --- maven/website/content/guides/mini/guide-new-committers.html (original) +++ maven/website/content/guides/mini/guide-new-committers.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-new-committers.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-new-committers.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide for new committers <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-new-committers.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide for new committers <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-new-committers.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -123,30 +123,12 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide for new committers</h2> -<p>First thing is to sort out some administrative tasks. Before your account is created and commit access granted you must complete and fax back to Apache the <a href="http://www.apache.org/licenses/#clas"; class="externalLink">Committer's License Agreement</a>.</p> -<p>While this process is sorting itself out it is recommended that you peruse the various guides provided by Apache. All the guides are located in the <a href="http://www.apache.org/dev/"; class="externalLink">Development Infrastructure Information</a>.</p> -<p>Of particular interest is the <a href="http://www.apache.org/dev/committers.html"; class="externalLink">Committer's FAQ</a> and the <a href="http://www.apache.org/dev/new-committers-guide.html"; class="externalLink">New Committer's Guide</a>.</p> -<p>If you have any questions please feel free to ask any of the Maven developers.</p></section></section> +<section> +<h1>Guide for new committers</h1> +<p>First thing is to sort out some administrative tasks. Before your account is created and commit access granted you must complete and fax back to Apache the <a class="externalLink" href="http://www.apache.org/licenses/#clas";>Committer's License Agreement</a>.</p> +<p>While this process is sorting itself out it is recommended that you peruse the various guides provided by Apache. All the guides are located in the <a class="externalLink" href="http://www.apache.org/dev/";>Development Infrastructure Information</a>.</p> +<p>Of particular interest is the <a class="externalLink" href="http://www.apache.org/dev/committers.html";>Committer's FAQ</a> and the <a class="externalLink" href="http://www.apache.org/dev/new-committers-guide.html";>New Committer's Guide</a>.</p> +<p>If you have any questions please feel free to ask any of the Maven developers.</p></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-proxies.html ============================================================================== --- maven/website/content/guides/mini/guide-proxies.html (original) +++ maven/website/content/guides/mini/guide-proxies.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-proxies.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-proxies.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to using proxies <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-proxies.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to using proxies <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-proxies.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -152,30 +152,11 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Configuring a proxy</h2> -<p>You can configure a proxy to use for some or all of your HTTP requests with Maven. The username and password are only required if your proxy requires basic authentication (note that later releases may support storing your passwords in a secured keystore - in the mean time, please ensure your settings.xml file (usually <code>${user.home}/.m2/settings.xml</code>) is secured with permissions appropriate for your operating system).</p> +<section> +<h1>Configuring a proxy</h1> +<p>You can configure a proxy to use for some or all of your HTTP requests with Maven. The username and password are only required if your proxy requires basic authentication (note that later releases may support storing your passwords in a secured keystore - in the mean time, please ensure your settings.xml file (usually ${user.home}/.m2/settings.xml) is secured with permissions appropriate for your operating system).</p> <p>The <code>nonProxyHosts</code> setting accepts wild cards, and each host not to proxy is separated by the | character. This matches the JDK configuration equivalent.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<div class="source"><pre class="prettyprint linenums"> <settings> . . @@ -194,12 +175,12 @@ under the License. . . </settings> - -</code></pre></div> +</pre></div> <p>Please note that currently NTLM proxies are not supported as they have not been tested. You may be able to use the relevant system properties on JDK 1.4+ to make this work.</p><section> -<h3>Resources</h3> -<p>1 <a href="../../maven-settings/settings.html">Settings descriptor documentation</a></p> -<p>1 <a href="./guide-configuring-maven.html">Configuring Maven</a></p></section></section></section> +<h2>Resources</h2> +<ol style="list-style-type: decimal"> +<li><a href="../../maven-settings/settings.html">Settings descriptor documentation</a></li> +<li><a href="./guide-configuring-maven.html">Configuring Maven</a></li></ol></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-releasing.html ============================================================================== --- maven/website/content/guides/mini/guide-releasing.html (original) +++ maven/website/content/guides/mini/guide-releasing.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-releasing.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-releasing.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,8 +10,12 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Jason van Zyl, Trent Rosenbaum, Vincent Massol , Karl Heinz Marbaise" /> - <meta name="date" content="2006-10-07, 2015-07-31" /> + <meta name="author" content="Jason van Zyl +Trent Rosenbaum +Vincent Massol +Karl Heinz Marbaise" /> + <meta name="date" content="2006-10-07 +2015-07-31" /> <title>Maven – Guide to using the release plugin</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> @@ -48,7 +52,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to using the release plugin <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-releasing.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to using the release plugin <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-releasing.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -154,57 +158,35 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Releasing</h2><section> -<h3>Introduction</h3> +<section> +<h1>Releasing</h1><section> +<h2>Introduction</h2> <p>The main aim of the maven-release plugin is to provide a standard mechanism to release project artifacts outside the immediate development team. The plugin provides basic functionality to create a release and to update the project's SCM accordingly.</p> <p>To create a release the maven-release plugin is executed through maven in 2 stages:</p> -<p>1 Preparing the release.</p> -<p>1 Performing the release.</p></section><section> -<h3>Preparing the release</h3> -<p>The plugin will record release information into a new revision of the project's <em>pom.xml</em> file as well as applying SCM versioning to the project's resources.</p> +<ol style="list-style-type: decimal"> +<li>Preparing the release.</li> +<li>Performing the release.</li></ol></section><section> +<h2>Preparing the release</h2> +<p>The plugin will record release information into a new revision of the project's <i>pom.xml</i> file as well as applying SCM versioning to the project's resources.</p> <p>The <code>release:prepare</code> goal will:</p> -<p>1 Verify that there are no uncommitted changes in the workspace.</p> -<p>1 Prompt the user for the desired tag, release and development version names.</p> -<p>1 Modify and commit release information into the <em>pom.xml</em> file.</p> -<p>1 Tag the entire project source tree with the new tag name.</p> +<ol style="list-style-type: decimal"> +<li>Verify that there are no uncommitted changes in the workspace.</li> +<li>Prompt the user for the desired tag, release and development version names.</li> +<li>Modify and commit release information into the <i>pom.xml</i> file.</li> +<li>Tag the entire project source tree with the new tag name.</li></ol> <p>The following example shows how to run the <code>release:prepare</code> goal with a Subversion SCM. The commandline example directs the plugin to locate a Subversion SCM on a local file system.</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn release:prepare \ +<div> +<pre>mvn release:prepare \ -Dproject.scm.developerConnection=scm:svn:file:///D:/subversion_data/repos/my_repo/my-app-example/trunk \ - -DtagBase=file:///D:/subversion_data/repos/my_repo/my-app-example/tags -</code></pre></div> + -DtagBase=file:///D:/subversion_data/repos/my_repo/my-app-example/tags</pre></div> <p>When using the <code>release:prepare</code> goal, the user must supply maven with information regarding the current location of the project's SCM. In the previous example maven was supplied with the current location of the development trunk and the new location to record tagged instances of the project.</p> <ul> - -<li> -<p><strong>project.scm.developerConnection</strong></p> -<p>The current location of the development trunk. A valid SCM URL format appropriate to the SCM provider. The “SCM:Provider:” prefix is used to determine the provider being used.</p></li> -<li> -<p><strong>tagbase</strong></p> -<p>The new location to record a tagged release. A valid SCM URL format appropriate to the SCM provider without the “SCM:Provider:” prefix.</p></li> -</ul> -<p>The previous goal parameters can be supplied while executing maven on the commandline, (as shown in the previous example) or they can be defined and maintained within the project's <em>pom.xml</em> file. The location of the current development trunk is defined within the <em>pom.xml</em> file in the following form:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<li><b>project.scm.developerConnection</b> +<p>The current location of the development trunk. A valid SCM URL format appropriate to the SCM provider. The "SCM:Provider:" prefix is used to determine the provider being used.</p></li> +<li><b>tagbase</b> +<p>The new location to record a tagged release. A valid SCM URL format appropriate to the SCM provider without the "SCM:Provider:" prefix.</p></li></ul> +<p>The previous goal parameters can be supplied while executing maven on the commandline, (as shown in the previous example) or they can be defined and maintained within the project's <i>pom.xml</i> file. The location of the current development trunk is defined within the <i>pom.xml</i> file in the following form:</p> +<div class="source"><pre class="prettyprint linenums"><project> <modelVersion>4.0.0</modelVersion> <groupId>com.mycompany.app</groupId> <artifactId>app</artifactId> @@ -235,11 +217,9 @@ under the License. </plugins> </build> ... -</project> -</code></pre></div> -<p>To define the tagBase parameter within the <em>pom.xml</em> file a tagBase element must be defined within a <em>plugins/plugin/configuration</em> element. The following example shows how this would look within the <em>pom.xml</em> file.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +</project> </pre></div> +<p>To define the tagBase parameter within the <i>pom.xml</i> file a tagBase element must be defined within a <i>plugins/plugin/configuration</i> element. The following example shows how this would look within the <i>pom.xml</i> file.</p> +<div class="source"><pre class="prettyprint linenums"><project> <modelVersion>4.0.0</modelVersion> <groupId>com.mycompany.app</groupId> <artifactId>app</artifactId> @@ -270,36 +250,30 @@ under the License. </plugins> </build> ... -</project> -</code></pre></div> +</project></pre></div> <p>During the execution of the <code>release:prepare</code> goal maven will interact with the user to gather information about the current release. Maven will prompt the user for the following information:</p> <ul> - -<li> -<p><strong>A Desired SCM provider tag name</strong>.</p> -<p>This is a SCM provider specific value, in the case of the Subversion SCM provider this value is equal to the directory name that will appear under the URL provided by the the tagBase parameter.</p></li> -<li> -<p><strong>A Desired project release version</strong>.</p> -<p>This value is placed in the <em>pom.xml</em> that will define the current release. If a development <em>pom.xml</em> holds a version value of 1.0-SNAPSHOT then the release version would be 1.0. This is not enforced and can be a value appropriate to yourself or a company environment.</p></li> -<li> -<p><strong>A New development version</strong>.</p> -<p>This value is the placed in the next revision of the <em>pom.xml</em> file used for continuing development. If the current release represented version 1.0 then an appropriate value could be 2.0-SNAPSHOT. The SNAPSHOT designator is required to prepare and perform future releases. This value is then committed in the next development revision of the <em>pom.xml</em> file.</p></li> -</ul> +<li><b>A Desired SCM provider tag name</b>. +<p>This is a SCM provider specific value, in the case of the Subversion SCM provider this value is equal to the folder name that will appear under the URL provided by the the tagBase parameter.</p></li> +<li><b>A Desired project release version</b>. +<p>This value is placed in the <i>pom.xml</i> that will define the current release. If a development <i>pom.xml</i> holds a version value of 1.0-SNAPSHOT then the release version would be 1.0. This is not enforced and can be a value appropriate to yourself or a company environment.</p></li> +<li><b>A New development version</b>. +<p>This value is the placed in the next revision of the <i>pom.xml</i> file used for continuing development. If the current release represented version 1.0 then an appropriate value could be 2.0-SNAPSHOT. The SNAPSHOT designator is required to prepare and perform future releases. This value is then committed in the next development revision of the <i>pom.xml</i> file.</p></li></ul> <p>After maven has been supplied with the required information the maven-release plugin will interact with the project's SCM and define a relese to be extracted and deployed. At the same time the project's development trunk is updated allowing developers to continue with further modifications that will be included within future releases.</p></section><section> -<h3>Performing the release</h3> +<h2>Performing the release</h2> <p>The plugin will extract file revisions associated with the current release. Maven will compile, test and package the versioned project source code into an artifact. The final deliverable will then be released into an appropriate maven repository.</p> <p>The <code>release:perform</code> goal will:</p> -<p>1 Extract file revisions versioned under the new tag name.</p> -<p>1 Execute the maven build lifecycle on the extracted instance of the project.</p> -<p>1 Deploy the versioned artifacts to appropriate local and remote repositories.</p> +<ol style="list-style-type: decimal"> +<li>Extract file revisions versioned under the new tag name.</li> +<li>Execute the maven build lifecycle on the extracted instance of the project.</li> +<li>Deploy the versioned artifacts to appropriate local and remote repositories.</li></ol> <p>The following example shows how to run the <code>release:perform</code> goal from the commandline.</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn release:perform -</code></pre></div> -<p>The <code>release:perform</code> goal requires a file called <em>release.properties</em> to be present within the project root directory. The <em>release.properties</em> file is constructed during the execution of the <code>release:prepare</code> goal and contains all the information needed to locate and extract the correctly tagged version of the project. Shown below is an example of the contents that can appear within an instance of the <em>release.properties</em> file.</p> -<p><strong>Note:</strong> The location of the <em>release.properties</em> file is under review and could be moved to the target directory.</p> - -<div class="source"><pre class="prettyprint linenums"><code>#Generated by Release Plugin on: Sat Nov 12 11:22:33 GMT 2005 +<div> +<pre>mvn release:perform</pre></div> +<p>The <code>release:perform</code> goal requires a file called <i>release.properties</i> to be present within the project root directory. The <i>release.properties</i> file is constructed during the execution of the <code>release:prepare</code> goal and contains all the information needed to locate and extract the correctly tagged version of the project. Shown below is an example of the contents that can appear within an instance of the <i>release.properties</i> file.</p> +<p><b>Note:</b> The location of the <i>release.properties</i> file is under review and could be moved to the target directory.</p> +<div> +<pre>#Generated by Release Plugin on: Sat Nov 12 11:22:33 GMT 2005 #Sat Nov 12 11:22:33 GMT 2005 maven.username=myusername checkpoint.transformed-pom-for-release=OK @@ -312,13 +286,11 @@ checkpoint.initialized=OK checkpoint.checked-in-release-version=OK checkpoint.tagged-release=OK checkpoint.prepared-release=OK -checkpoint.check-in-development-version=OK -</code></pre></div> -<p>The <em>release.properties</em> file is created while preparing the release. After performing the release the file remains within the project root directory until the maven user deletes it. The <em>release.properties</em> file can be given to any developer within the team and by simply excuting the <code>release:perform</code> goal can create and deploy a new instance of the project artifact time and again.</p> -<p>During the execution of the <code>release:perform</code> goal the entire maven build lifecycle is executed on the project. The tagged project source code is extracted, compiled, tested, documented and deployed. An instance of the release artifact is deployed to the machine's local repository. An another instance of the release can be deployed to a remote repository by configuring the <em>distributionManagement</em> element within the <em>pom.xml</em> file.</p> -<p>The following is an example of how a distributionManagement element can be configured within a project <em>pom.xml</em> file.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +checkpoint.check-in-development-version=OK</pre></div> +<p>The <i>release.properties</i> file is created while preparing the release. After performing the release the file remains within the project root directory until the maven user deletes it. The <i>release.properties</i> file can be given to any developer within the team and by simply excuting the <code>release:perform</code> goal can create and deploy a new instance of the project artifact time and again.</p> +<p>During the execution of the <code>release:perform</code> goal the entire maven build lifecycle is executed on the project. The tagged project source code is extracted, compiled, tested, documented and deployed. An instance of the release artifact is deployed to the machine's local repository. An another instance of the release can be deployed to a remote repository by configuring the <i>distributionManagement</i> element within the <i>pom.xml</i> file.</p> +<p>The following is an example of how a distributionManagement element can be configured within a project <i>pom.xml</i> file.</p> +<div class="source"><pre class="prettyprint linenums"><project> <modelVersion>4.0.0</modelVersion> <groupId>com.mycompany.app</groupId> <artifactId>app</artifactId> @@ -335,30 +307,23 @@ checkpoint.check-in-development-version= </repository> </distributionManagement> ... -</project> -</code></pre></div> -<p>If the distributionManagement element is not configured within the <em>pom.xml</em> file then the deployment of the artifact will fail. Maven will report a failure back to the user for the execution of the maven-deploy plugin. Please refer maven documentationa and additional mini guides for the use of the maven-deploy plugin.</p> +</project></pre></div> +<p>If the distributionManagement element is not configured within the <i>pom.xml</i> file then the deployment of the artifact will fail. Maven will report a failure back to the user for the execution of the maven-deploy plugin. Please refer maven documentationa and additional mini guides for the use of the maven-deploy plugin.</p> <p>The following delvierables are created and deployed to local and remoted repositories after the execution of the <code>release:perform</code> goal has finished.</p> <ul> - -<li> -<p><em>artifact id</em>-<em>version</em>.jar</p> +<li><i>artifact id</i>-<i>version</i>.jar <p>The binaries for the current release of the project.</p></li> -<li> -<p><em>artifact id</em>-<em>version</em>-javadoc.jar</p> +<li><i>artifact id</i>-<i>version</i>-javadoc.jar <p>The javadoc explaining the current functionality of the classes within the current release.</p></li> -<li> -<p><em>artifact id</em>-<em>version</em>-source.jar</p> +<li><i>artifact id</i>-<i>version</i>-source.jar <p>The source code revisions used to build the current release of the project.</p></li> -<li> -<p><em>artifact id</em>-<em>version</em>.pom</p> -<p>The contents of the <em>pom.xml</em> file used to create the current release of the project.</p></li> -</ul></section><section> -<h3>Troubleshooting</h3><section> -<h4>I get a “The authenticity of host ‘<em>host</em>’ can't be established.” error and the build hangs</h4> -<p>This is because your <code>\~user/.ssh/known_hosts</code> file doesn't have the host listed. You'd normally get a prompt to add the host to the known host list but Maven doesn't propagate that prompt. The solution is to add the host the <code>known_hosts</code> file before executing Maven. On Windows, this can be done by installing an OpenSSH client (for example <a href="http://sshwindows.sourceforge.net/download/"; class="externalLink">SSHWindows</a>), running <code>ssh <host></code> and accepting to add the host.</p></section><section> -<h4>The site deploy goal hangs</h4> -<p>First, this means that you have successfully deployed the artifacts to the remote repo and that it's only the site deployment that is now an issue. Stop your build, cd to <strong>target/checkout</strong>> and run the build again by executing <code>mvn site:deploy</code>. You should see a prompt asking you to enter a password. This happens if your key is not in the authorized keys on the server.</p></section></section></section></section> +<li><i>artifact id</i>-<i>version</i>.pom +<p>The contents of the <i>pom.xml</i> file used to create the current release of the project.</p></li></ul></section><section> +<h2>Troubleshooting</h2><section> +<h3>I get a "The authenticity of host '<i>host</i>' can't be established." error and the build hangs</h3> +<p>This is because your <code>~user/.ssh/known_hosts</code> file doesn't have the host listed. You'd normally get a prompt to add the host to the known host list but Maven doesn't propagate that prompt. The solution is to add the host the <code>known_hosts</code> file before executing Maven. On Windows, this can be done by installing an OpenSSH client (for example <a class="externalLink" href="http://sshwindows.sourceforge.net/download/";>SSHWindows</a>), running <code>ssh <host</code>> and accepting to add the host.</p></section><section> +<h3>The site deploy goal hangs</h3> +<p>First, this means that you have successfully deployed the artifacts to the remote repo and that it's only the site deployment that is now an issue. Stop your build, cd to <b>target/checkout</b>> and run the build again by executing <code>mvn site:deploy</code>. You should see a prompt asking you to enter a password. This happens if your key is not in the authorized keys on the server.</p></section></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-relocation.html ============================================================================== --- maven/website/content/guides/mini/guide-relocation.html (original) +++ maven/website/content/guides/mini/guide-relocation.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-relocation.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-relocation.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to relocation <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-relocation.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to relocation <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-relocation.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -152,40 +152,22 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to relocation</h2> +<section> +<h1>Guide to relocation</h1> <p>Sometimes it is necessary to relocate artifacts in the repository. One example of that is when a project moves from one groupId to a different groupId.</p> <p>Making changes to the repository can have far reaching consequences. So it is best to get it right the first time, hence this guide.</p> -<p><strong>2020 rework in progress</strong>, see <a href="https://lists.apache.org/thread.html/r5e940260cfe5234f540c20fdb7bb7dacbb63b911a4b902c75f4f0cd2%40%3Cdev.maven.apache.org%3E"; class="externalLink">discussion on dev mailing list</a>, still need analysis of issues, definition of improvements, and of course implementation…</p><section> -<h3>How to relocate a Maven 2 artifact to a different groupId</h3> +<p><b>2020 rework in progress</b>, see <a class="externalLink" href="https://lists.apache.org/thread.html/r5e940260cfe5234f540c20fdb7bb7dacbb63b911a4b902c75f4f0cd2%40%3Cdev.maven.apache.org%3E";>discussion on dev mailing list</a>, still need analysis of issues, definition of improvements, and of course implementation...</p><section> +<h2>How to relocate a Maven 2 artifact to a different groupId</h2> <p>The goal of the example below is for the <code>foo</code> project to relocate its groupId from <code>bar</code> to <code>org.bar</code>.</p><section> -<h4>Working on past versions</h4> -<p>1 Copy all <code>foo</code>-related files from <code>/bar/foo/</code> in your Maven 2 repository to a temporary location.</p> -<p>1 Change the groupId to <code>org.bar</code> in all <code>foo</code>-related POM files in the temporary location.</p> -<p>1 Copy all files from the temporary location to <code>/org/bar/foo/</code> in your Maven 2 repository.</p> -<p>1 Create a minimal Maven 2 POM file for every old release of <code>foo</code> in your Maven 2 repository. The POM files only need to include <code>groupId</code>, <code>artifactId</code>, <code>version</code> and the relocation section.</p> -<p><strong>Note:</strong> Before you replace your old POM files in <code>/bar/foo/</code> with these minimal POM files, make sure you have made backups!</p> +<h3>Working on past versions</h3> +<ol style="list-style-type: decimal"> +<li>Copy all <code>foo</code>-related files from <code>/bar/foo/</code> in your Maven 2 repository to a temporary location.</li> +<li>Change the groupId to <code>org.bar</code> in all <code>foo</code>-related POM files in the temporary location.</li> +<li>Copy all files from the temporary location to <code>/org/bar/foo/</code> in your Maven 2 repository.</li> +<li>Create a minimal Maven 2 POM file for every old release of <code>foo</code> in your Maven 2 repository. The POM files only need to include <code>groupId</code>, <code>artifactId</code>, <code>version</code> and the relocation section. +<p><b>Note:</b> Before you replace your old POM files in <code>/bar/foo/</code> with these minimal POM files, make sure you have made backups!</p> <p>The minimal POM file might look like this for version 1.0 of <code>foo</code>:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> <modelVersion>4.0.0</modelVersion> <groupId>bar</groupId> <artifactId>foo</artifactId> @@ -195,27 +177,28 @@ under the License. <groupId>org.bar</groupId> </relocation> </distributionManagement> -</project> -</code></pre></div> -<p>In this case we are relocating because the groupId has changed. We only need to add the element that has changed to the <code>relocation</code> element. For information on which elements are allowed in the <code>relocation</code> element, see <a href="/ref/current/maven-model/maven.html#class_relocation">the POM reference</a>.</p> -<p>1 If your project uses MD5 or SHA1 checksums you must now create new checksums for the pom files in <code>/bar/foo/</code> in your Maven 2 repository. If the POM file needs to be signed, do that as well.</p> -<p>1 If your project syncs with Central, you should now initiate that sync. This might happen automatically depending on your projects sync policy.</p> +</project></pre></div> +<p>In this case we are relocating because the groupId has changed. We only need to add the element that has changed to the <code>relocation</code> element. For information on which elements are allowed in the <code>relocation</code> element, see <a href="/ref/current/maven-model/maven.html#class_relocation">the POM reference</a>.</p></li> +<li>If your project uses MD5 or SHA1 checksums you must now create new checksums for the pom files in <code>/bar/foo/</code> in your Maven 2 repository. If the POM file needs to be signed, do that as well.</li> +<li>If your project syncs with Central, you should now initiate that sync. This might happen automatically depending on your projects sync policy.</li></ol> <p>Your <code>foo</code>-artifacts are now available to Maven users with both the old and the new groupId. Projects using the old groupId will automatically be redirected to the new groupId and a warning telling the user to update their dependencies will be issued.</p></section><section> -<h4>Releasing the next version</h4> +<h3>Releasing the next version</h3> <p>When the next release of <code>foo</code> is made, you should publish two Maven 2 POM files: first you should publish <code>foo</code>'s POM with the new groupId <code>org.bar</code>.</p> <p>Because data in the repository is not supposed to change, Maven doesn't download POM files that it has already downloaded. Therefore you will also need to publish a relocation POM file with the old groupId <code>bar</code> for the new version: this should be a minimal relocation POM (as described in step 4 above), but for the new version of <code>foo</code>.</p> <p>For the release after that, you only need to publish a Maven POM with a groupId of <code>org.bar</code>, since users of the previous version have been informed of the changed groupId.</p></section></section><section> -<h3>Examples</h3><section> -<h4>Apache Ant</h4> -<p>1 has published its releases until 1.6.5 to Maven 1-compliant <code>ant:ant</code> coordinates (see <a href="https://repo.maven.apache.org/maven2/ant/ant/"; class="externalLink">repository content</a>),</p> -<p>1 starting with 1.7.0, moved to reverse-DNS compliant Maven 2+ <code>org.apache.ant:ant</code> coordinates, (see <a href="https://repo.maven.apache.org/maven2/org/apache/ant/ant/"; class="externalLink">repository content</a>),</p> -<p>1 published one <code>ant:ant:1.7.0</code> relocation POM in old groupId to advertise about the move (see <a href="https://repo.maven.apache.org/maven2/ant/ant/1.7.0/"; class="externalLink">repository content</a>).</p> +<h2>Examples</h2><section> +<h3>Apache Ant</h3> +<ol style="list-style-type: decimal"> +<li>has published its releases until 1.6.5 to Maven 1-compliant <code>ant:ant</code> coordinates (see <a class="externalLink" href="https://repo.maven.apache.org/maven2/ant/ant/";>repository content</a>),</li> +<li>starting with 1.7.0, moved to reverse-DNS compliant Maven 2+ <code>org.apache.ant:ant</code> coordinates, (see <a class="externalLink" href="https://repo.maven.apache.org/maven2/org/apache/ant/ant/";>repository content</a>),</li> +<li>published one <code>ant:ant:1.7.0</code> relocation POM in old groupId to advertise about the move (see <a class="externalLink" href="https://repo.maven.apache.org/maven2/ant/ant/1.7.0/";>repository content</a>).</li></ol> <p>Notice that past <code>ant:ant</code> versions POMs (until 1.6.5) have not been modified to advertise about the move: Central POM content is not expected to be changed once published (because initial content has been downloaded many times and is not expected to be re-loaded later).</p></section><section> -<h4>Apache POI</h4> -<p>1 has published its releases until 3.0-alpha-3 to Maven 1-compliant <code>poi:poi</code> coordinates (see <a href="https://repo.maven.apache.org/maven2/poi/poi/"; class="externalLink">repository content</a>),</p> -<p>1 starting with 3.0-FINAL, moved to reverse-DNS compliant Maven 2+ <code>org.apache.poi:poi</code> coordinates, (see <a href="https://repo.maven.apache.org/maven2/org/apache/poi/poi/"; class="externalLink">repository content</a>),</p> -<p>1 published <code>poi:poi:3.0-FINAL</code> relocation POM <strong>with jars</strong> in old groupId to advertise about the move (see <a href="https://repo.maven.apache.org/maven2/poi/poi/3.0-FINAL/"; class="externalLink">repository content</a>).</p> -<p>1 published <code>poi:poi</code> relocation POMs for 3.0.1-FINAL, 3.0.2-beta1/beta2/FINAL and 3.1-beta1/beta2/FINAL in old groupId to advertise about the move (see <a href="https://repo.maven.apache.org/maven2/poi/poi/"; class="externalLink">repository content</a>).</p></section></section></section></section> +<h3>Apache POI</h3> +<ol style="list-style-type: decimal"> +<li>has published its releases until 3.0-alpha-3 to Maven 1-compliant <code>poi:poi</code> coordinates (see <a class="externalLink" href="https://repo.maven.apache.org/maven2/poi/poi/";>repository content</a>),</li> +<li>starting with 3.0-FINAL, moved to reverse-DNS compliant Maven 2+ <code>org.apache.poi:poi</code> coordinates, (see <a class="externalLink" href="https://repo.maven.apache.org/maven2/org/apache/poi/poi/";>repository content</a>),</li> +<li>published <code>poi:poi:3.0-FINAL</code> relocation POM <b>with jars</b> in old groupId to advertise about the move (see <a class="externalLink" href="https://repo.maven.apache.org/maven2/poi/poi/3.0-FINAL/";>repository content</a>).</li> +<li>published <code>poi:poi</code> relocation POMs for 3.0.1-FINAL, 3.0.2-beta1/beta2/FINAL and 3.1-beta1/beta2/FINAL in old groupId to advertise about the move (see <a class="externalLink" href="https://repo.maven.apache.org/maven2/poi/poi/";>repository content</a>).</li></ol></section></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-repository-ssl.html ============================================================================== --- maven/website/content/guides/mini/guide-repository-ssl.html (original) +++ maven/website/content/guides/mini/guide-repository-ssl.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-repository-ssl.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-repository-ssl.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Remote repository access through authenticated HTTPS <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-repository-ssl.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Remote repository access through authenticated HTTPS <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-repository-ssl.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -152,53 +152,32 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to Remote repository access through authenticated HTTPS</h2> +<section> +<h1>Guide to Remote repository access through authenticated HTTPS</h1> <p>This document describes how to configure Maven to access a remote repository that sits behind an HTTPS server which requires client authentication with certificates.</p><section> -<h3>The problem</h3> +<h2>The problem</h2> <p>There is a maven repository at <code>https://my.server.com/maven</code>. This server only serves clients authenticated through SSL protocol by a valid certificate signed by an approved certificate authority's certificate which we call the <code>CACert</code>. In the simplest case where the server is used internally by an identified community of users (e.g. corporate intranet), the server's certificate is the certificate authority as the server is used only internally.</p> <p>So we assume that we have access to the trusted certificate in X.509 format stored in a file named:</p> - -<div class="source"><pre class="prettyprint linenums"><code> /somewhere/in/filesystem/CACert.cert -</code></pre></div> +<div> +<pre> /somewhere/in/filesystem/CACert.cert</pre></div> <p>The client's certificate has been issued by some means not described in this document in PKCS#12 format, which is the format that is accepted by browsers (at least Firefox and Internet Explorer) for import into their keystore. This file is named:</p> - -<div class="source"><pre class="prettyprint linenums"><code> /home/directory/mycertificate.p12 -</code></pre></div> +<div> +<pre> /home/directory/mycertificate.p12</pre></div> <p>and we assume it is accessible when launching maven. This file contains the client's private key which may be very sensitive information so it is secured by a password:</p> - -<div class="source"><pre class="prettyprint linenums"><code> CeRtPwD -</code></pre></div> +<div> +<pre> CeRtPwD</pre></div> <p>The remote repository is referenced either through the <code>pom.xml</code> file:</p> - -<div class="source"><pre class="prettyprint linenums"><code>maven.repo.remote=https://my.server.com/maven,http://www.ibiblio.org/maven -</code></pre></div></section><section> -<h3>The solution</h3> +<div> +<pre>maven.repo.remote=https://my.server.com/maven,http://www.ibiblio.org/maven</pre></div></section><section> +<h2>The solution</h2> <p>For maven to use this repository, we should take the following steps:</p> -<p>1 Create a store to hold the server's certificate usings Oracle's <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html"; class="externalLink">keytool</a>,</p> -<p>1 Define properties to be used by HttpClient for finding keys and certificate</p><section> -<h4>Storing certificate</h4> -<p>The following command line imports the certififcate authority's certificate into a JKS formatted key store named <code>trust.jks</code>, the <em>trust store</em>.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-bash">$> keytool -v -alias mavensrv -import \ +<ol style="list-style-type: decimal"> +<li>Create a store to hold the server's certificate usings Oracle's <a class="externalLink" href="https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html";> keytool</a>,</li> +<li>Define properties to be used by HttpClient for finding keys and certificate</li></ol><section> +<h3>Storing certificate</h3> +<p>The following command line imports the certififcate authority's certificate into a JKS formatted key store named <code>trust.jks</code>, the <i>trust store</i>.</p> +<div> +<pre>$> keytool -v -alias mavensrv -import \ -file /somewhere/in/filesystem/CACert.cert\ -keystore trust.jks Enter keystore password: @@ -212,32 +191,35 @@ Certificate fingerprints: Trust this certificate? [no]: yes Certificate was added to keystore [Storing trust.jks] -$> -</code></pre></div> +$></pre></div> <p>Note that it should be possible to import a full chain of certificates with only one root certificate being trusted but the author did not test it.</p></section><section> -<h4>Setting properties</h4> +<h3>Setting properties</h3> <p>The following properties must be set at start of maven to be accessible when HttpClient starts up.</p> -<p>[javax.net.ssl.trustStore] the path to the keystore where trusted certificates are stored</p> -<p>[javax.net.ssl.trustStoreType] the type of storage for this store, maybe either <code>jks</code> (default) or <code>pkcs12</code></p> -<p>[javax.net.ssl.trustStorePassword] the password protecting the store</p> -<p>[javax.net.ssl.keyStore] the path to the keystore where user's private key is stored</p> -<p>[javax.net.ssl.keyStoreType] the type of storage for this store, maybe either <code>jks</code> (default) or <code>pkcs12</code></p> -<p>[javax.net.ssl.keyStorePassword] the password protecting the store</p> +<dl> +<dt>javax.net.ssl.trustStore</dt> +<dd>the path to the keystore where trusted certificates are stored</dd> +<dt>javax.net.ssl.trustStoreType</dt> +<dd>the type of storage for this store, maybe either <code>jks</code> (default) or <code>pkcs12</code></dd> +<dt>javax.net.ssl.trustStorePassword</dt> +<dd>the password protecting the store</dd> +<dt>javax.net.ssl.keyStore</dt> +<dd>the path to the keystore where user's private key is stored</dd> +<dt>javax.net.ssl.keyStoreType</dt> +<dd>the type of storage for this store, maybe either <code>jks</code> (default) or <code>pkcs12</code></dd> +<dt>javax.net.ssl.keyStorePassword</dt> +<dd>the password protecting the store</dd></dl> <p>Not all the properties must be set depending of your precise settings: type of store may left to default, password may be empty.</p> <p>They may be set either on maven's command-line, in <code>.mavenrc</code> file or in <code>MAVEN_OPTS</code> environment variable. For the setting defined in this document, here is an example <code>.mavenrc</code> file:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-bash">MAVEN_OPTS="-Xmx512m -Djavax.net.ssl.trustStore=trust.jks \ +<div> +<pre>MAVEN_OPTS="-Xmx512m -Djavax.net.ssl.trustStore=trust.jks \ -Djavax.net.ssl.trustStorePassword= \ -Djavax.net.ssl.keyStore=/home/directory/mycertificate.p12 \ -Djavax.net.ssl.keyStoreType=pkcs12 \ - -Djavax.net.ssl.keyStorePassword=XXXXXX" -</code></pre></div></section></section><section> -<h3>Links</h3> + -Djavax.net.ssl.keyStorePassword=XXXXXX"</pre></div></section></section><section> +<h2>Links</h2> <p>The following links may be useful in understanding SSL infrastructure management in Java:</p> <ul> - -<li><a href="http://hc.apache.org/httpclient-3.x/sslguide.html"; class="externalLink">HttpClient</a>'s SSL guide</li> -</ul></section></section></section> +<li><a class="externalLink" href="http://hc.apache.org/httpclient-3.x/sslguide.html";> HttpClient</a>'s SSL guide</li></ul></section></section> </main> </div> </div>
