You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-commits@maven.apache.org by sv...@apache.org on 2023/02/08 20:32:15 UTC
svn commit: r1907529 [12/22] - in /maven/website/content: ./ apache-resource-bundles/ archives/maven-2.x/ background/ developers/ developers/conventions/ developers/release/ developers/website/ docs/ docs/2.0.1/ docs/2.0.10/ docs/2.0.11/ docs/2.0.2/ do...
Modified: maven/website/content/guides/mini/guide-configuring-plugins.html
==============================================================================
--- maven/website/content/guides/mini/guide-configuring-plugins.html (original)
+++ maven/website/content/guides/mini/guide-configuring-plugins.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-configuring-plugins.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-configuring-plugins.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="Jason van Zyl
Vincent Siveton" />
<meta name="date" content="2009-08-26" />
@@ -143,7 +143,7 @@ Vincent Siveton" />
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Guide_to_Configuring_Plug-ins"></a>Guide to Configuring Plug-ins</h1>
+<h1>Guide to Configuring Plug-ins</h1>
<ul>
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#Generic_Configuration">Generic Configuration</a>
@@ -168,14 +168,14 @@ Vincent Siveton" />
<li><a href="#Using_the_.3Creporting.3E_Tag_VS_.3Cbuild.3E_Tag">Using the <reporting> Tag VS <build> Tag</a></li>
<li><a href="#Using_the_.3CreportSets.3E_Tag">Using the <reportSets> Tag</a></li>
<li><a href="#Using_the_.3Cinherited.3E_Tag_In_Reporting_Plugins">Using the <inherited> Tag In Reporting Plugins</a></li></ul></li></ul><section>
-<h2><a name="Introduction"></a>Introduction</h2>
+<h2>Introduction</h2>
<p>In Maven, there are two kinds of plugins, build and reporting:</p>
<ul>
<li><b>Build plugins</b> are executed during the build and configured in the <code><build/></code> element.</li>
<li><b>Reporting plugins</b> are executed during the site generation and configured in the <code><reporting/></code> element.</li></ul>
<p>All plugins should have minimal required <a href="/ref/current/maven-model/maven.html#class_plugin">information</a>: <code>groupId</code>, <code>artifactId</code> and <code>version</code>.</p>
<p><b>Important Note</b>: Always define the version of each plugin used to guarantee build reproducibility. A good practice is to specify each build plugin's version in a <code><build><pluginManagement/></build></code> element. Often the <pluginManagement/> element is found in the parent POM. For reporting plugins, specify each version in the <code><reporting><plugins/></reporting></code> element (and in the <code><build><pluginManagement/></build></code> element too).</p></section><section>
-<h2><a name="Generic_Configuration">Generic Configuration</a></h2>
+<h2><a id="Generic_Configuration">Generic Configuration</a></h2>
<p>Maven plugins (build and reporting) are configured by specifying a <code><configuration></code> element where the child elements of the <code><configuration></code> element are mapped to fields, or setters, inside your Mojo. (Remember that a plug-in consists of one or more Mojos where a Mojo maps to a goal.) Say, for example, you have a Mojo that performs a query against a particular URL, with a specified timeout and list of options. The Mojo might look like the following:</p>
<div class="source"><pre class="prettyprint linenums">@Mojo( name = "query" )
public class MyQueryMojo
@@ -223,14 +223,14 @@ public class MyQueryMojo
<div>
<pre>mvn myquery:query -Dquery.url=http://maven.apache.org</pre></div>
<p>The name of the system property does not necessarily match the name of the mojo parameter. While this is a rather common practice, you will often notice plugins that employ some prefix for the system properties to avoid name clashes with other system properties. Though rarely, there are also plugin parameters that (e.g. for historical reasons) employ system properties which are completely unrelated to the parameter name. So be sure to have a close look at the plugin documentation.</p><section>
-<h3><a name="Help_Goal">Help Goal</a></h3>
+<h3><a id="Help_Goal">Help Goal</a></h3>
<p>Most Maven plugins have a <code>help</code> goal that prints a description of the plugin and its parameters and types. For instance, to see help for the javadoc goal, type:</p>
<div>
<pre>mvn javadoc:help -Ddetail -Dgoal=javadoc</pre></div>
<p>And you will see all parameters for the javadoc:javadoc goal, similar to this <a href="/plugins/maven-javadoc-plugin/javadoc-mojo.html">page</a>.</p></section><section>
-<h3><a name="Configuring_Parameters">Configuring Parameters</a></h3>
+<h3><a id="Configuring_Parameters">Configuring Parameters</a></h3>
<p>Parametrisation of Mojos is relying internally on Plexus Component Configuration API provided by <a class="externalLink" href="https://github.com/eclipse/sisu.plexus">sisu-plexus</a>.</p><section>
-<h4><a name="Mapping_Value_Objects">Mapping Value Objects</a></h4>
+<h4><a id="Mapping_Value_Objects">Mapping Value Objects</a></h4>
<p>Mapping value types, like Boolean or Integer, is very simple. The <code><configuration></code> element might look like the following:</p>
<div class="source"><pre class="prettyprint linenums"><project>
...
@@ -245,62 +245,62 @@ public class MyQueryMojo
...
</project></pre></div>
<p>The detailed type coercion is explained in the table below. For conversion to primitive types their according <a class="externalLink" href="https://docs.oracle.com/javase/tutorial/java/data/autoboxing.html">wrapper classes are used and automatically unboxed</a>.</p>
-<table border="1" class="table table-striped">
+<table class="bodyTable bodyTableBorder">
<tr class="a">
-<th align="center">Parameter Class</th>
-<th align="center">Conversion from String</th></tr>
+<th>Parameter Class</th>
+<th>Conversion from String</th></tr>
<tr class="b">
-<td align="center"><code>Boolean</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html#valueOf-java.lang.String-"><code>Boolean.valueOf(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Boolean</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html#valueOf-java.lang.String-"><code>Boolean.valueOf(String)</code></a></td></tr>
<tr class="a">
-<td align="center"><code>Byte</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Byte.html#decode-java.lang.String-"><code>Byte.decode(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Byte</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Byte.html#decode-java.lang.String-"><code>Byte.decode(String)</code></a></td></tr>
<tr class="b">
-<td align="center"><code>Character</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Character.html#valueOf-char-"><code>Character.valueOf(char)</code></a> of the first character in the given string</td></tr>
+<td style="text-align: center;"><code>Character</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Character.html#valueOf-char-"><code>Character.valueOf(char)</code></a> of the first character in the given string</td></tr>
<tr class="a">
-<td align="center"><code>Class</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#forName-java.lang.String-"><code>Class.forName(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Class</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#forName-java.lang.String-"><code>Class.forName(String)</code></a></td></tr>
<tr class="b">
-<td align="center"><code>java.util.Date</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/text/DateFormat.html#parse-java.lang.String-"><code>SimpleDateFormat.parse(String)</code></a> for the following patterns: <code>yyyy-MM-dd hh:mm:ss.S a</code>, <code>yyyy-MM-dd hh:mm:ssa</code>, <code>yyyy-MM-dd HH:mm:ss.S</code> or <code>yyyy-MM-dd HH:mm:ss</code></td></tr>
+<td style="text-align: center;"><code>java.util.Date</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/text/DateFormat.html#parse-java.lang.String-"><code>SimpleDateFormat.parse(String)</code></a> for the following patterns: <code>yyyy-MM-dd hh:mm:ss.S a</code>, <code>yyyy-MM-dd hh:mm:ssa</code>, <code>yyyy-MM-dd HH:mm:ss.S</code> or <code>yyyy-MM-dd HH:mm:ss</code></td></tr>
<tr class="a">
-<td align="center"><code>Double</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html#valueOf-java.lang.String-"><code>Double.valueOf(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Double</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html#valueOf-java.lang.String-"><code>Double.valueOf(String)</code></a></td></tr>
<tr class="b">
-<td align="center"><code>Enum</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html#valueOf-java.lang.String-"><code>Enum.valueOf(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Enum</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html#valueOf-java.lang.String-"><code>Enum.valueOf(String)</code></a></td></tr>
<tr class="a">
-<td align="center"><code>java.io.File</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/io/File.html#File-java.lang.String-"><code>new File(String)</code></a> with the file separators normalized to <code>File.separatorChar</code>. In case the file is relative, is is made absolute by prefixing it with the project's base directory.</td></tr>
+<td style="text-align: center;"><code>java.io.File</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/io/File.html#File-java.lang.String-"><code>new File(String)</code></a> with the file separators normalized to <code>File.separatorChar</code>. In case the file is relative, is is made absolute by prefixing it with the project's base directory.</td></tr>
<tr class="b">
-<td align="center"><code>Float</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Float.html#valueOf-java.lang.String-"><code>Float.valueOf(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Float</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Float.html#valueOf-java.lang.String-"><code>Float.valueOf(String)</code></a></td></tr>
<tr class="a">
-<td align="center"><code>Integer</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-"><code>Integer.decode(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Integer</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-"><code>Integer.decode(String)</code></a></td></tr>
<tr class="b">
-<td align="center"><code>Long</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html#decode-java.lang.String-"><code>Long.decode(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Long</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html#decode-java.lang.String-"><code>Long.decode(String)</code></a></td></tr>
<tr class="a">
-<td align="center"><code>Short</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Short.html#decode-java.lang.String-"><code>Short.decode(String)</code></a></td></tr>
+<td style="text-align: center;"><code>Short</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Short.html#decode-java.lang.String-"><code>Short.decode(String)</code></a></td></tr>
<tr class="b">
-<td align="center"><code>String</code></td>
-<td align="center">n/a</td></tr>
+<td style="text-align: center;"><code>String</code></td>
+<td style="text-align: center;">n/a</td></tr>
<tr class="a">
-<td align="center"><code>StringBuffer</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuffer.html#StringBuffer-java.lang.String-"><code>new StringBuffer(String)</code></a></td></tr>
+<td style="text-align: center;"><code>StringBuffer</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuffer.html#StringBuffer-java.lang.String-"><code>new StringBuffer(String)</code></a></td></tr>
<tr class="b">
-<td align="center"><code>StringBuilder</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html#StringBuilder-java.lang.String-"><code>new StringBuilder(String)</code></a></td></tr>
+<td style="text-align: center;"><code>StringBuilder</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html#StringBuilder-java.lang.String-"><code>new StringBuilder(String)</code></a></td></tr>
<tr class="a">
-<td align="center"><code>java.net.URI</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html#URI-java.lang.String-"><code>new URI(String)</code></a></td></tr>
+<td style="text-align: center;"><code>java.net.URI</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html#URI-java.lang.String-"><code>new URI(String)</code></a></td></tr>
<tr class="b">
-<td align="center"><code>java.net.URL</code></td>
-<td align="center"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#URL-java.lang.String-"><code>new URL(String)</code></a></td></tr></table></section><section>
-<h4><a name="Mapping_Complex_Objects">Mapping Complex Objects</a></h4>
+<td style="text-align: center;"><code>java.net.URL</code></td>
+<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#URL-java.lang.String-"><code>new URL(String)</code></a></td></tr></table></section><section>
+<h4><a id="Mapping_Complex_Objects">Mapping Complex Objects</a></h4>
<p>Mapping complex types is also fairly straight forward. Let's look at a simple example where we are trying to map a configuration for Person object. The <code><configuration/></code> element might look like the following:</p>
<div class="source"><pre class="prettyprint linenums"><project>
...
@@ -327,9 +327,9 @@ public class MyQueryMojo
</configuration>
...
</project></pre></div></section><section>
-<h4><a name="Mapping_Collection_Types">Mapping Collection Types</a></h4>
+<h4><a id="Mapping_Collection_Types">Mapping Collection Types</a></h4>
<p>The configuration mapping mechanism can easily deal with most collections so let's go through a few examples to show you how it's done:</p><section>
-<h5><a name="Mapping_Collections_and_Arrays">Mapping Collections and Arrays</a></h5>
+<h5><a id="Mapping_Collections_and_Arrays">Mapping Collections and Arrays</a></h5>
<p>Mapping to collections works in much the same way as mapping to arrays. Each item is given in the XML as dedicated element. The element name does not matter in that case. So if you have a mojo like the following:</p>
<div class="source"><pre class="prettyprint linenums">public class MyAnimalMojo
extends AbstractMojo
@@ -387,7 +387,7 @@ public class MyQueryMojo
...
</project></pre></div>
<p>Each item is mapped again according to the rules of this section depending on the type of the collection/array.</p></section><section>
-<h5><a name="Mapping_Maps">Mapping Maps</a></h5>
+<h5><a id="Mapping_Maps">Mapping Maps</a></h5>
<p>In the same way, you could define maps like the following:</p>
<div class="source"><pre class="prettyprint linenums">...
@Parameter
@@ -405,7 +405,7 @@ public class MyQueryMojo
</project></pre></div>
<p>Unlike Collections the value type for Maps is always derived from the parameter type information from either <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Field.html#getGenericType()"><code>Field.getGenericType()</code></a> or <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Method.html#getGenericParameterTypes()"><code>Method.getGenericParameterTypes()</code></a>. It falls back to <code>String</code>. The key type must always be <code>String</code>.</p>
<p>In contrast to value objects and collections/arrays there is no string coercion defined for maps, i.e. you cannot give parameters of that type via CLI argument. </p></section><section>
-<h5><a name="Mapping_Properties">Mapping Properties</a></h5>
+<h5><a id="Mapping_Properties">Mapping Properties</a></h5>
<p>Properties should be defined like the following:</p>
<div class="source"><pre class="prettyprint linenums">...
@Parameter
@@ -428,9 +428,9 @@ public class MyQueryMojo
...
</project></pre></div>
<p>In contrast to value objects and collections/arrays there is no string coercion defined for properties, i.e. you cannot give parameters of those type via CLI argument. </p></section></section></section></section><section>
-<h2><a name="Configuring_Build_Plugins">Configuring Build Plugins</a></h2>
+<h2><a id="Configuring_Build_Plugins">Configuring Build Plugins</a></h2>
<p>The following is only to configure Build plugins in the <code><build></code> element.</p><section>
-<h3><a name="Using_the_.3Cexecutions.3E_Tag"></a><a name="Using_the_executions_Tag">Using the <code><executions></code> Tag</a></h3>
+<h3><a id="Using_the_executions_Tag">Using the <code><executions></code> Tag</a></h3>
<p>You can also configure a mojo using the <code><executions></code> tag. This is most commonly used for mojos that are intended to participate in some phases of the <a href="../introduction/introduction-to-the-lifecycle.html">build lifecycle</a>. Using <code>MyQueryMojo</code> as an example, you may have something that will look like:</p>
<div class="source"><pre class="prettyprint linenums"><project>
...
@@ -570,7 +570,7 @@ public class MyBoundQueryMojo
<p><b>Note:</b> Configurations inside the <code><executions></code> element used to differ from those that are outside <code><executions></code> in that they could not be used from a direct command line invocation because they were only applied when the lifecycle phase they were bound to was invoked. So you had to move a configuration section outside of the executions section to apply it globally to all invocations of the plugin. Since Maven 3.3.1 this is not the case anymore as you can specify on the command line the execution id for direct plugin goal invocation. Hence if you want to run the above plugin and it's specific execution1's configuration from the command-line, you can execute:</p>
<div>
<pre>mvn myquery:query@execution1</pre></div></section><section>
-<h3><a name="Using_the_.3Cdependencies.3E_Tag"></a><a name="Using_the_dependencies_Tag">Using the <code><dependencies></code> Tag</a></h3>
+<h3><a id="Using_the_dependencies_Tag">Using the <code><dependencies></code> Tag</a></h3>
<p>You could configure the dependencies of the Build plugins, commonly to use a more recent dependency version.</p>
<p>For instance, the Maven Antrun Plugin version 1.2 uses Ant version 1.6.5, if you want to use the latest Ant version when running this plugin, you need to add <code><dependencies></code> element like the following:</p>
<div class="source"><pre class="prettyprint linenums"><project>
@@ -599,7 +599,7 @@ public class MyBoundQueryMojo
</build>
...
</project></pre></div></section><section>
-<h3><a name="Using_the_.3Cinherited.3E_Tag_In_Build_Plugins"></a><a name="Using_the_inherited_Tag_In_Build_Plugins">Using the <code><inherited></code> Tag In Build Plugins</a></h3>
+<h3><a id="Using_the_inherited_Tag_In_Build_Plugins">Using the <code><inherited></code> Tag In Build Plugins</a></h3>
<p>By default, plugin configuration should be propagated to child POMs, so to break the inheritance, you could use the <code><inherited></code> tag:</p>
<div class="source"><pre class="prettyprint linenums"><project>
...
@@ -616,16 +616,16 @@ public class MyBoundQueryMojo
</build>
...
</project></pre></div></section></section><section>
-<h2><a name="Configuring_Reporting_Plugins">Configuring Reporting Plugins</a></h2>
+<h2><a id="Configuring_Reporting_Plugins">Configuring Reporting Plugins</a></h2>
<p>The following is only to configure Reporting plugins in the <code><reporting></code> element.</p><section>
-<h3><a name="Using_the_.3Creporting.3E_Tag_VS_.3Cbuild.3E_Tag"></a><a name="Using_the_reporting_Tag_VS_build_Tag">Using the <code><reporting></code> Tag VS <code><build></code> Tag</a></h3>
+<h3><a id="Using_the_reporting_Tag_VS_build_Tag">Using the <code><reporting></code> Tag VS <code><build></code> Tag</a></h3>
<p>Configuring a reporting plugin in the <code><reporting></code> or <code><build></code> elements in the pom does not exactly have the same results.</p>
<dl>
<dt><code>mvn site</code></dt>
<dd>Since maven-site-plugin 3.4, it uses the parameters defined in the <code><configuration></code> element of each reporting Plugin specified in the <code><reporting></code> element, in addition to the parameters defined in the <code><configuration></code> element of each plugin specified in <code><build></code> (parameters from <code><build></code> section were previously ignored).</dd>
<dt><code>mvn aplugin:areportgoal</code></dt>
<dd>It <b>ignores</b> the parameters defined in the <code><configuration></code> element of each reporting Plugin specified in the <code><reporting></code> element; only parameters defined in the <code><configuration></code> element of each plugin specified in <code><build></code> are used.</dd></dl></section><section>
-<h3><a name="Using_the_.3CreportSets.3E_Tag"></a><a name="Using_the_reportSets_Tag">Using the <code><reportSets></code> Tag</a></h3>
+<h3><a id="Using_the_reportSets_Tag">Using the <code><reportSets></code> Tag</a></h3>
<p>You can configure a reporting plugin using the <code><reportSets></code> tag. This is most commonly used to generate reports selectively when running <code>mvn site</code>. The following will generate only the project team report.</p>
<div class="source"><pre class="prettyprint linenums"><project>
...
@@ -656,7 +656,7 @@ public class MyBoundQueryMojo
</reportSet>
</reportSets></pre></div></li>
<li>Refer to each Plugin Documentation (i.e. plugin-info.html) to know the available report goals.</li></ol></section><section>
-<h3><a name="Using_the_.3Cinherited.3E_Tag_In_Reporting_Plugins"></a><a name="Using_the_inherited_Tag_In_Reporting_Plugins">Using the <code><inherited></code> Tag In Reporting Plugins</a></h3>
+<h3><a id="Using_the_inherited_Tag_In_Reporting_Plugins">Using the <code><inherited></code> Tag In Reporting Plugins</a></h3>
<p>Similar to the build plugins, to break the inheritance, you can use the <code><inherited></code> tag:</p>
<div class="source"><pre class="prettyprint linenums"><project>
...
Modified: maven/website/content/guides/mini/guide-creating-archetypes.html
==============================================================================
--- maven/website/content/guides/mini/guide-creating-archetypes.html (original)
+++ maven/website/content/guides/mini/guide-creating-archetypes.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-creating-archetypes.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-creating-archetypes.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="Jason van Zyl, Alexander Hars, Franz Allan Valencia See" />
<meta name="date" content="2010-04-10" />
<title>Maven – Guide to Creating Archetypes</title>
@@ -141,7 +141,7 @@
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Guide_to_Creating_Archetypes"></a>Guide to Creating Archetypes</h1>
+<h1>Guide to Creating Archetypes</h1>
<p>Creating an archetype is a pretty straight forward process. An archetype is a very simple artifact, that contains the project prototype you wish to create. An archetype is made up of:</p>
<ul>
<li>an <a href="/archetype/archetype-models/archetype-descriptor/archetype-descriptor.html">archetype descriptor</a> (<code>archetype-metadata.xml</code> in directory: <code>src/main/resources/META-INF/maven/</code>). It lists all the files that will be contained in the archetype and categorizes them so they can be processed correctly by the archetype generation mechanism.</li>
@@ -149,7 +149,7 @@
<li>the prototype pom (<code>pom.xml</code> in: <code>src/main/resources/archetype-resources</code>)</li>
<li>a pom for the archetype (<code>pom.xml</code> in the archetype's root directory).</li></ul>
<p>To create an archetype follow these steps:</p><section>
-<h2><a name="a1._Create_a_new_project_and_pom.xml_for_the_archetype_artifact"></a>1. Create a new project and pom.xml for the archetype artifact</h2>
+<h2>1. Create a new project and pom.xml for the archetype artifact</h2>
<p>An example <code>pom.xml</code> for an archetype artifact looks as follows:</p>
<div class="source"><pre class="prettyprint linenums">
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -173,7 +173,7 @@
</project>
</pre></div>
<p>All you need to specify is a <code>groupId</code>, <code>artifactId</code> and <code>version</code>. These three parameters will be needed later for invoking the archetype via <code>archetype:generate</code> from the commandline.</p></section><section>
-<h2><a name="a2._Create_the_archetype_descriptor"></a>2. Create the archetype descriptor</h2>
+<h2>2. Create the archetype descriptor</h2>
<p>The <a href="/archetype/archetype-models/archetype-descriptor/archetype-descriptor.html">archetype descriptor</a> is a file called <code>archetype-metadata.xml</code> which must be located in the <code>src/main/resources/META-INF/maven/</code> directory. An example of an archetype descriptor can be found in the quickstart archetype:</p>
<div class="source"><pre class="prettyprint linenums">
<archetype-descriptor
@@ -219,7 +219,7 @@ archetype
`-- java
`-- AppTest.java
</pre></div></section><section>
-<h2><a name="a3._Create_the_prototype_files_and_the_prototype_pom.xml"></a>3. Create the prototype files and the prototype pom.xml</h2>
+<h2>3. Create the prototype files and the prototype pom.xml</h2>
<p>The next component of the archetype to be created is the prototype <code>pom.xml</code>. Any <code>pom.xml</code> will do, just don't forget to the set <code>artifactId</code> and <code>groupId</code> as variables ( <code>${artifactId}</code> / <code>${groupId}</code> ). Both variables will be initialized from the commandline when calling <code>archetype:generate</code>.</p>
<p>An example for a prototype <code>pom.xml</code> is:</p>
<div class="source"><pre class="prettyprint linenums">
@@ -245,7 +245,7 @@ archetype
</dependencies>
</project>
</pre></div></section><section>
-<h2><a name="a4._Install_the_archetype_and_run_the_archetype_plugin"></a>4. Install the archetype and run the archetype plugin</h2>
+<h2>4. Install the archetype and run the archetype plugin</h2>
<p>Now you are ready to install the archetype:</p>
<div>
<pre>
@@ -262,7 +262,7 @@ mvn archetype:generate
-DartifactId=<my-artifactId>
</pre></div>
<p>Once you are happy with the state of your archetype, you can deploy (or submit it to <a href="/guides/mini/guide-central-repository-upload.html">Maven Central</a>) it as any other artifact and the archetype will then be available to any user of Maven.</p></section><section>
-<h2><a name="Alternative_way_to_start_creating_your_Archetype"></a>Alternative way to start creating your Archetype</h2>
+<h2>Alternative way to start creating your Archetype</h2>
<p>Instead of manually creating the directory structure needed for an archetype, simply use</p>
<div>
<pre>mvn archetype:generate
Modified: maven/website/content/guides/mini/guide-default-execution-ids.html
==============================================================================
--- maven/website/content/guides/mini/guide-default-execution-ids.html (original)
+++ maven/website/content/guides/mini/guide-default-execution-ids.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-default-execution-ids.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-default-execution-ids.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="John Casey" />
<meta name="date" content="2009-06-10" />
<title>Maven – Guide to Configuring Default Mojo Executions</title>
@@ -142,7 +142,7 @@
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Guide_to_Configuring_Default_Mojo_Executions"></a>Guide to Configuring Default Mojo Executions</h1>
+<h1>Guide to Configuring Default Mojo Executions</h1>
<p>In most cases where you need to configure a plugin, there are two options that work well: plugin-level configuration and execution-level configuration. Plugin-level configuration is the most common method for configuring plugins that will be used from the command line, are defined as part of the default lifecycle, or that use a common configuration across all invocations. In fact, for direct invocation from the command line, plugin-level configuration has been the <i>only</i> option historically.</p>
<p>On the other hand, in cases where a more advanced build process requires the execution of mojos - sometimes the same mojos, sometimes different ones - from a single plugin that use different configurations, the execution-level configuration is most commonly used. These cases normally involve plugins that are introduced as part of the standard build process, but which aren't present in the default lifecycle mapping for that particular packaging. In these cases, common settings shared between executions are still normally specified in the plugin-level configuration.</p>
<p>However, these two options leave out a few important configuration use cases: </p>
@@ -150,9 +150,9 @@
<li>Mojos run from the command line <i>and</i> during the build, when the CLI-driven invocation requires its own configuration.</li>
<li>Mojo executions that are bound to the lifecycle as part of the default mapping for a particular packaging, especially in cases where the same mojos need to be added to a second execution with different configuration.</li>
<li>Groups of mojos from the same plugin that are bound to the lifecycle as part of the default mapping for a particular packaging, but require separate configurations.</li></ul><section>
-<h2><a name="Default_executionIds_for_Implied_Executions"></a>Default <code>executionId</code>s for Implied Executions</h2>
+<h2>Default <code>executionId</code>s for Implied Executions</h2>
<p>When you consider the fact that the aforementioned configuration use cases are for mojos that are not explicitly mentioned in the POM, it's reasonable to refer to them as implied executions. But if they're implied, how can Maven allow users to provide configuration for them? The solution we've implemented is rather simple and low-tech, but should be more than adequate to handle even advanced use cases. Starting in Maven 2.2.0, each mojo invoked directly from the command line will have an execution Id of <code>default-cli</code> assigned to it, which will allow the configuration of that execution from the POM by using this default execution Id. Likewise, each mojo bound to the build lifecycle via the default lifecycle mapping for the specified POM packaging will have an execution Id of <code>default-<goalName></code> assigned to it, to allow configuration of each default mojo execution independently.</p><section>
-<h3><a name="Example:_Command-line_variant_invocation_of_the_assembly_plugin"></a>Example: Command-line variant invocation of the assembly plugin</h3>
+<h3>Example: Command-line variant invocation of the assembly plugin</h3>
<p>Consider the case where the user wants to execute the <code>assembly:assembly</code> mojo directly on the command line, but already has a configuration for the <code>assembly:single</code> mojo that runs during the main build lifecycle. Since these configurations require different options, the user cannot use the plugin-level configuration section to specify common elements.</p>
<p>In this case, the assembly-plugin configuration might look like this:</p>
<div class="source"><pre class="prettyprint linenums"><plugin>
@@ -187,7 +187,7 @@
</plugin></pre></div>
<p>In the above example, you can see several interesting things. First, the main build process will invoke the <code>assembly:single</code> mojo during the <code>package</code> phase of the build, and produce both binary and source distribution artifacts using custom assembly descriptors included with the project. Second, all invocations of the assembly plugin should use a <code>tarLongFileMode</code> strategy of <code>gnu</code>. Finally, when the assembly plugin is invoked from the command line, it will build the standard <code>jar-with-dependencies</code> and <code>project</code> artifacts for the project, and ignore the custom assembly descriptors in <code>src/main/assembly</code>.</p>
<p>Now, notice the difference in the way the two execution blocks reference assembly descriptors. One uses custom descriptors via the <code>descriptors</code> section, and the other uses standard descriptors via the <code>descriptorRefs</code> section. These two sections cannot override one another, so it's impossible to setup one section - say, <code>descriptorRefs</code> - in the plugin-level configuration block (to provide CLI access to it, as historical versions of Maven would require), then have the <code>build-distros</code> invocation override it with the custom descriptors specified in the <code>descriptors</code> section.</p></section><section>
-<h3><a name="Example:_Configuring_compile_to_run_twice"></a>Example: Configuring <code>compile</code> to run twice</h3>
+<h3>Example: Configuring <code>compile</code> to run twice</h3>
<p>In this scenario, the user wants to run the <code>compiler:compile</code> mojo twice for his <code>jar</code> packaging project. The main reason for this is to provide an entry point into the application that will warn the user if he's using a Java version older than 1.5, then exit gracefully. Without such an entry point, the user would be confronted with a stacktrace in the event he tried to run this application with a 1.4 or older JRE.</p>
<p>Therefore, the user needs to compile the bulk of his application to target the 1.5 Java specification, then compile the rest (the entry point) to target an older specification...say, 1.3. The first execution will specify the <code>source</code> and <code>target</code> values at <code>1.5</code>, and add an <code>excludes</code> section to avoid compiling the entry point for the application. The second pass will then re-specify <code>source</code> and <code>target</code> to <code>1.3</code>, and basically invert the original <code>excludes</code> section to be an <code>includes</code> section, so as to compile <i>only</i> the entry point class.</p>
<p>The resulting configuration might look something like this:</p>
@@ -227,7 +227,7 @@
<li>The default <code>source</code> and <code>target</code> compatibility levels are for Java 1.5. This means that the compiler will generate binaries for Java 1.5 from both the main codebase and the test codebase, unless otherwise overridden.</li>
<li>The default pass of the <code>compile</code> goal will <i>exclude</i> the <code>**/cli/*</code> path pattern, but will compile everything else in <code>src/main/java</code> to run under Java 1.5.</li>
<li>The second pass of the <code>compile</code> mojo - in the execution called <code>build-java14-cli</code> - resets the <code>source</code> and <code>target</code> versions to <code>1.3</code>, and inverts the exclude rule from the first pass. This means the second time around, the compiler will produce 1.4-targeted binaries for the classes matching the <code>**/cli/*</code> path pattern.</li></ul></section><section>
-<h3><a name="Example:_Configuring_compile_and_testCompile_mojos_separately"></a>Example: Configuring <code>compile</code> and <code>testCompile</code> mojos separately</h3>
+<h3>Example: Configuring <code>compile</code> and <code>testCompile</code> mojos separately</h3>
<p>Finally, building on our use of the compiler plugin to tease out these different use cases, consider the case where a user wants to target version 1.4 of the Java specification as his runtime platform. However, he still wants the convenience and other advantages to be found in a unit-testing framework like TestNG. This forces the user to configure the <code>compile</code> mojo with one set of <code>source</code> and <code>target</code> values - specifically, <code>1.4</code> - and the <code>testCompile</code> mojo with another (<code>1.5</code>).</p>
<p>The resulting compiler-plugin configuration might look something like the following:</p>
<div class="source"><pre class="prettyprint linenums"><plugin>
Modified: maven/website/content/guides/mini/guide-deployment-security-settings.html
==============================================================================
--- maven/website/content/guides/mini/guide-deployment-security-settings.html (original)
+++ maven/website/content/guides/mini/guide-deployment-security-settings.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-deployment-security-settings.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-deployment-security-settings.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="Jason van Zyl" />
<meta name="date" content="2005-10-12" />
<title>Maven – Guide to Deployment and Security Settings</title>
@@ -153,7 +153,7 @@
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Security_and_Deployment_Settings"></a>Security and Deployment Settings</h1>
+<h1>Security and Deployment Settings</h1>
<p>Repositories to deploy to are defined in a project in the <code>distributionManagement</code> section. However, you cannot put your username, password, or other security settings in that project. For that reason, you should add a server definition to your own settings with an id that matches that of the deployment repository in the project.</p>
<p>In addition, some repositories may require authorisation to download from, so the corresponding settings can be specified in a server element in the same way.</p>
<p>Which settings are required will depend on the type of repository you are deploying to. As of the first release, only SCP deployments and file deployments are supported by default, so only the following SCP configuration is needed:</p>
Modified: maven/website/content/guides/mini/guide-encryption.html
==============================================================================
--- maven/website/content/guides/mini/guide-encryption.html (original)
+++ maven/website/content/guides/mini/guide-encryption.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-encryption.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-encryption.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="Oleg Gusakov
Robert Scholte" />
<meta name="date" content="2014-03-23" />
@@ -154,14 +154,14 @@ Robert Scholte" />
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Password_Encryption">Password Encryption</a></h1>
+<h1><a id="Password_Encryption">Password Encryption</a></h1>
<ol style="list-style-type: decimal">
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#How_to_create_a_master_password">How to create a master password</a></li>
<li><a href="#How_to_encrypt_server_passwords">How to encrypt server passwords</a></li>
<li><a href="#How_to_keep_the_master_password_on_removable_drive">How to keep the master password on removable drive</a></li>
<li><a href="#Tips">Tips</a></li></ol><section>
-<h2><a name="Introduction">Introduction</a></h2>
+<h2><a id="Introduction">Introduction</a></h2>
<p>Maven supports server password encryption. The main use case, addressed by this solution is:</p>
<ul>
<li>multiple users share the same build machine (server, CI box)</li>
@@ -179,7 +179,7 @@ Robert Scholte" />
<li>server entries in the <code>settings.xml</code> have passwords and/or keystore passphrases encrypted
<ul>
<li>for now - this is done via CLI <b>after</b> master password has been created and stored in appropriate location</li></ul></li></ul></section><section>
-<h2><a name="How_to_create_a_master_password">How to create a master password</a></h2>
+<h2><a id="How_to_create_a_master_password">How to create a master password</a></h2>
<p>Use the following command line:</p>
<div>
<pre>mvn --encrypt-master-password <password></pre></div>
@@ -192,7 +192,7 @@ Robert Scholte" />
<master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
</settingsSecurity></pre></div>
<p>When this is done, you can start encrypting existing server passwords.</p></section><section>
-<h2><a name="How_to_encrypt_server_passwords">How to encrypt server passwords</a></h2>
+<h2><a id="How_to_encrypt_server_passwords">How to encrypt server passwords</a></h2>
<p>You have to use the following command line:</p>
<div>
<pre>mvn --encrypt-password <password></pre></div>
@@ -233,7 +233,7 @@ Robert Scholte" />
<pre>mvn deploy:deploy-file -Durl=https://maven.corp.com/repo \
-DrepositoryId=my.server \
-Dfile=your-artifact-1.0.jar \</pre></div></section><section>
-<h2><a name="How_to_keep_the_master_password_on_removable_drive">How to keep the master password on removable drive</a></h2>
+<h2><a id="How_to_keep_the_master_password_on_removable_drive">How to keep the master password on removable drive</a></h2>
<p>Create the master password exactly as described above, and store it on a removable drive, for instance on OSX, my USB drive mounts as <code>/Volumes/mySecureUsb</code>, so I store</p>
<div class="source"><pre class="prettyprint linenums"><settingsSecurity>
<master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
@@ -244,8 +244,8 @@ Robert Scholte" />
<relocation>/Volumes/mySecureUsb/secure/settings-security.xml</relocation>
</settingsSecurity></pre></div>
<p>This assures that encryption only works when the USB drive is mounted by the OS. This addresses a use case where only certain people are authorized to deploy and are issued these devices.</p></section><section>
-<h2><a name="Tips">Tips</a></h2><section>
-<h3><a name="Escaping_curly-brace_literals_in_your_password_.28Since:_Maven_2.2.0.29"></a>Escaping curly-brace literals in your password <i>(Since: Maven 2.2.0)</i></h3>
+<h2><a id="Tips">Tips</a></h2><section>
+<h3>Escaping curly-brace literals in your password <i>(Since: Maven 2.2.0)</i></h3>
<p>At times, you might find that your password (or the encrypted form of it) contains '{' or '}' as a literal value. If you added such a password as-is to your settings.xml file, you would find that Maven does strange things with it. Specifically, Maven treats all the characters preceding the '{' literal, and all the characters after the '}' literal, as comments. Obviously, this is not the behavior you want. What you really need is a way of <b>escaping</b> the curly-brace literals in your password.</p>
<p>You can do this with the widely used '\' escape character. If your password looks like this:</p>
<div>
@@ -253,13 +253,13 @@ Robert Scholte" />
<p>Then, the value you would add to your settings.xml looks like this:</p>
<div>
<pre>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+\{EF1iFQyJQ=}</pre></div></section><section>
-<h3><a name="Password_Security"></a>Password Security</h3>
+<h3>Password Security</h3>
<p>Editing <code>settings.xml</code> and running the above commands can still leave your password stored locally in plaintext. You may want to check the following locations:</p>
<ul>
<li>Shell history (e.g. by running <code>history</code>). You may want to clear your history after encrypting the above passwords</li>
<li>Editor caches (e.g. <code>~/.viminfo</code>)</li></ul>
<p>Also note that the encrypted passwords can be decrypted by someone that has the master password and settings security file. Keep this file secure (or stored separately) if you expect the possibility that the <code>settings.xml</code> file may be retrieved.</p></section><section>
-<h3><a name="Password_Escaping_on_different_platforms"></a>Password Escaping on different platforms</h3>
+<h3>Password Escaping on different platforms</h3>
<p>On some platforms it might be necessary to quote the password if it contains special characters like <code>%</code>, <code>!</code>, <code>$</code>, etc. For example on Windows you have to be careful about things like the following:</p>
<p>The following example will not work on Windows:</p>
<div>
@@ -268,7 +268,7 @@ Robert Scholte" />
<div>
<pre>mvn --encrypt-master-password "a!$%^b"</pre></div>
<p>If you are on a linux/unix platform you should use single quotes for the above master password. Otherwise the master password will not work (caused by the dollar sign and the exclamation mark).</p></section><section>
-<h3><a name="Prompting_for_Password"></a>Prompting for Password</h3>
+<h3>Prompting for Password</h3>
<p>In Maven before version 3.2.1 you have to give the password on the command line as an argument which means you might need to escape your password. In addition usually the shell stores the full history of commands you have entered, therefore anyone with access to your computer could restore the password from the shell`s history.</p>
<p>Starting with Maven 3.2.1, the password is an optional argument. If you omit the password, you will be prompted for it which prevents all the issues mentioned above.</p>
<p>We strongly recommend using Maven 3.2.1 and above to prevent problems with escaping special characters and of course security issues related to bash history or environment issues in relationship with the password.</p></section></section></section>
Modified: maven/website/content/guides/mini/guide-generating-sources.html
==============================================================================
--- maven/website/content/guides/mini/guide-generating-sources.html (original)
+++ maven/website/content/guides/mini/guide-generating-sources.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-generating-sources.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-generating-sources.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="Jason van Zyl
Karl Heinz Marbaise" />
<meta name="date" content="2005-10-12
@@ -157,7 +157,7 @@ Karl Heinz Marbaise" />
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Guide_to_generating_sources"></a>Guide to generating sources</h1>
+<h1>Guide to generating sources</h1>
<p>Let's run though a short example to try and help. To generate sources you must first have a plugin that participates in the <code>generate-sources</code> phase like the <a class="externalLink" href="http://www.antlr.org/api/maven-plugin/latest/">ANTLR4 Maven Plugin</a>.</p>
<p>So this is all fine and dandy, we have a plugin that wants to generate some sources from a Antlr4 grammar but how do we use it. You need to specify that you want to use it in your POM:</p>
<div class="source"><pre class="prettyprint linenums">
Modified: maven/website/content/guides/mini/guide-http-settings.html
==============================================================================
--- maven/website/content/guides/mini/guide-http-settings.html (original)
+++ maven/website/content/guides/mini/guide-http-settings.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-http-settings.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-http-settings.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="John Casey" />
<meta name="date" content="2011-12-12" />
<title>Maven – Guide to Advanced HTTP Transport Configuration</title>
@@ -153,7 +153,7 @@
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Advanced_Configuration_of_the_Maven_Resolver_Transport"></a>Advanced Configuration of the Maven Resolver Transport</h1>
+<h1>Advanced Configuration of the Maven Resolver Transport</h1>
<ul>
<li><a href="#Advanced_Configuration_of_the_Maven_Resolver_Transport">Advanced Configuration of the Maven Resolver Transport</a>
<ul>
@@ -175,15 +175,15 @@
<li><a href="#Ignoring_Cookies">Ignoring Cookies</a></li></ul></li>
<li><a href="#Support_for_General-Wagon_Configuration_Standards">Support for General-Wagon Configuration Standards</a>
<ul>
-<li><a href="#HTTP_Headers">HTTP Headers</a></li>
-<li><a href="#Connection_Timeouts">Connection Timeouts</a></li>
+<li><a href="#HTTP_Headers_1">HTTP Headers</a></li>
+<li><a href="#Connection_Timeouts_1">Connection Timeouts</a></li>
<li><a href="#Read_time_out">Read time out</a></li></ul></li>
<li><a href="#Resources">Resources</a></li></ul></li></ul></li></ul>
<p>You can use the default transport for a given protocol, or you can select the transport you want by using the configuration. For more information about existing Resolver transports see the <a class="externalLink" href="https://maven.apache.org/resolver/"> Resolver</a> site. The default transport in Maven 3.x is Transport-Wagon, the Wagon layer having been introduced in Maven 2.x. Since then, more modern transports were introduced as well, even supporting overlapping protocols. The default transport in Maven 4.x changed to the more modern <a class="externalLink" href="https://maven.apache.org/resolver/maven-resolver-transport-http/index.html">"native" HTTP</a> transport.</p>
<p>Ultimate reference for resolver transport configuration can be found on <a class="externalLink" href="https://maven.apache.org/resolver/configuration.html"> this page</a>. While one can easily define simple typed values on command line using <code>-D...</code> switch, some more complex values, like HTTP headers, cannot.</p><section>
-<h2><a name="Advanced_configuration_to_Transports"></a>Advanced configuration to Transports</h2>
+<h2>Advanced configuration to Transports</h2>
<p>Using your <code>settings.xml</code> you can customize the transport configurations in several ways.</p><section>
-<h3><a name="HTTP_Headers"></a>HTTP Headers</h3>
+<h3>HTTP Headers</h3>
<p>In all HTTP transports, you can add your custom HTTP headers like this:</p>
<div class="source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -201,7 +201,7 @@
</servers>
</settings></pre></div>
<p>It is important to understand that the above approach does not allow you to turn off all of the default HTTP headers; nor does it allow you to specify headers on a per-method basis. However, this configuration remains available in all transports that support headers, like HTTP transports are.</p></section><section>
-<h3><a name="Connection_Timeouts"></a>Connection Timeouts</h3>
+<h3>Connection Timeouts</h3>
<p>All transport implementations that perform some network access allow the configuration of a several timeouts, for example to allow the user to tell Maven how long to wait before giving up on a connection that has not responded.</p>
<div class="source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -216,15 +216,15 @@
</settings></pre></div>
<p>These above define per-server timeout configuration, and show default values.</p>
<p>These are the standard ways to configure transport, regarding custom headers, and various timeouts. Each transport MAY introduce it's own specific configuration, like we can see below for Wagon.</p></section></section><section>
-<h2><a name="Advanced_Configuration_of_the_HttpClient_HTTP_Wagon"></a>Advanced Configuration of the HttpClient HTTP Wagon</h2>
+<h2>Advanced Configuration of the HttpClient HTTP Wagon</h2>
<p>You can use the default wagon implementation for a given protocol, or you can select an alternative wagon <code>provider</code> on a per-protocol basis. For more information, see the <a href="./guide-wagon-providers.html">Guide to Wagon Providers</a> [3]. The default wagon http(s) is the HttpClient based on <a class="externalLink" href="https://hc.apache.org/httpcomponents-client-4.5.x/">Apache Http Client 4.5</a>. HTTP connection pooling prevents reopening new connections to the same server for each request. This pool feature is configurable with some parameters [4]. The default wagon comes with some default configuration:</p>
<ul>
<li>http(s) connection pool: default to 20.</li>
<li>readTimeout: default to 1,800,000ms (~30 minutes) (see section <code>Read time out</code> below)</li>
<li>default Preemptive Authentication only with PUT (GET doesn't use anymore default Preemptive Authentication)</li></ul><section>
-<h3><a name="Introduction"></a>Introduction</h3>
+<h3>Introduction</h3>
<p>The HttpClient-based HTTP wagon offers more control over the configuration used to access HTTP-based Maven repositories. For starters, you have fine-grained control over what HTTP headers are used when resolving artifacts. In addition, you can also configure a wide range of parameters to control the behavior of HttpClient itself. Best of all, you have the ability to control these headers and parameters for all requests, or individual request types (GET, HEAD, and PUT).</p></section><section>
-<h3><a name="The_Basics"></a>The Basics</h3>
+<h3>The Basics</h3>
<p>Without any special configuration, Maven's HTTP wagon uses some default HTTP headers and client parameters when managing artifacts. The default headers are:</p>
<div>
<pre>Cache-control: no-cache
@@ -252,7 +252,7 @@ problems with HTTP servers and proxies t
<p>Without this setting, PUT requests that require authentication transfer their entire payload to the server before that server issues an authentication challenge. In order to complete the PUT request, the client must then re-send the payload with the proper credentials specified in the HTTP headers. This results in twice the bandwidth usage, and twice the time to transfer each artifact.</p>
<p>Another option to avoid this double transfer is what's known as preemptive authentication, which involves sending the authentication headers along with the original PUT request. However, there are a few potential issues with this approach. For one thing, in the event you have an unused <code><server></code> entry that specifies an invalid username/password combination, some servers may respond with a <code>401 Unauthorized</code> even if the server doesn't actually require any authentication for the request. In addition, blindly sending authentication credentials with every request regardless of whether the server has made a challenge can result in a security hole, since the server may not make provisions to secure credentials for paths that don't require authentication.</p>
<p>We'll discuss preemptive authentication in another example, below.</p></section><section>
-<h3><a name="Configuring_GET.2C_HEAD.2C_PUT.2C_or_All_of_the_Above"></a>Configuring GET, HEAD, PUT, or All of the Above</h3>
+<h3>Configuring GET, HEAD, PUT, or All of the Above</h3>
<p>In all of the examples below, it's important to understand that you can configure the HTTP settings for all requests made to a given server, or for only one method. To configure all methods for a server, use the following section of the <code>settings.xml</code> file:</p>
<div class="source"><pre class="prettyprint linenums"><settings>
[...]
@@ -286,7 +286,7 @@ problems with HTTP servers and proxies t
</servers>
</settings></pre></div>
<p>For clarity, the other two sections are <code><get></code> for GET requests, and <code><head></code> for HEAD requests. I know that's going to be hard to remember...</p></section><section>
-<h3><a name="Taking_Control_of_Your_HTTP_Headers"></a>Taking Control of Your HTTP Headers</h3>
+<h3>Taking Control of Your HTTP Headers</h3>
<p>As you may have noticed above, the default HTTP headers do have the potential to cause problems. For instance, some websites set the encoding for downloading GZipped files as <code>gzip</code>, in spite of the fact that the HTTP request itself isn't being sent using GZip compression. If the client is using the <code>Accept-Encoding: gzip</code> header, this can result in the client itself decompressing the GZipped file <i>during the transfer</i> and writing the decompressed file to the local disk with the original filename. This can be misleading to say the least, and can use up an inordinate amount of disk space on the local computer.</p>
<p>To turn off this default behavior, simply disable the default headers. Then, respecify the other headers that you are still interested in, like this:</p>
<div class="source"><pre class="prettyprint linenums"><settings>
@@ -328,9 +328,9 @@ problems with HTTP servers and proxies t
</servers>
[...]
</settings></pre></div></section><section>
-<h3><a name="Fine-Tuning_HttpClient_Parameters"></a>Fine-Tuning HttpClient Parameters</h3>
+<h3>Fine-Tuning HttpClient Parameters</h3>
<p>Going beyond the power of HTTP request parameters, HttpClient provides a host of other configuration options. In most cases, you won't need to customize these. But in case you do, Maven provides access to specify your own fine-grained configuration for HttpClient. Again, you can specify these parameter customizations per-method (HEAD, GET, or PUT), or for all methods of interacting with a given server. For a complete list of supported parameters, see the link[2] in Resources section below.</p><section>
-<h4><a name="Non-String_Parameter_Values"></a>Non-String Parameter Values</h4>
+<h4>Non-String Parameter Values</h4>
<p>Many of the configuration parameters for HttpClient have simple string values; however, there are important exceptions to this. In some cases, you may need to specify boolean, integer, or long values. In others, you may even need to specify a collection of string values. You can specify these using a simple formatting syntax, as follows:</p>
<ol style="list-style-type: decimal">
<li><b>booleans:</b> <code>%b,<value></code></li>
@@ -345,7 +345,7 @@ problems with HTTP servers and proxies t
<value3>,
...</pre></div></li></ol>
<p>As you may have noticed, this syntax is similar to the format-and-data strategy used by functions like <code>sprintf()</code> in many languages. The syntax has been chosen with this similarity in mind, to make it a little more intuitive to use.</p></section><section>
-<h4><a name="Example:_Using_Preemptive_Authentication"></a>Example: Using Preemptive Authentication</h4>
+<h4>Example: Using Preemptive Authentication</h4>
<p>Using the above syntax, you can configure preemptive authentication for PUT requests using the boolean HttpClient parameter <code>http.authentication.preemptive</code>, like this:</p>
<div class="source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -381,9 +381,9 @@ problems with HTTP servers and proxies t
</server>
</servers>
</settings></pre></div></section><section>
-<h4><a name="Example:_Lifting_auth_scope_restriction_for_external_authentication_systems"></a>Example: Lifting auth scope restriction for external authentication systems</h4>
+<h4>Example: Lifting auth scope restriction for external authentication systems</h4>
<p>Maven Wagon by default limits supplied credentials to the host:port combination scope, ignoring any other target servers. When the target server delegates authentication to an external system, you need to deliberately lift that scope limitation. Configure your server element to pass authentication to all target servers which challenge the client. +---+ <i>settings</i> <i>servers</i> <i>server</i> <i>id</i>my-server<i>/id</i> <i>configuration</i> <i>basicAuthScope</i> <i>host</i>ANY<i>/host</i> <i>port</i>ANY<i>/port</i> <i>!-- or even 443 to force the use of TLS --</i> <i>/basicAuthScope</i> <i>httpConfiguration</i> <i>all</i> <i>params</i> <i>property</i> <i>name</i>http.protocol.cookie-policy<i>/name</i> <i>value</i>standard<i>/value</i> <i>/property</i> <i>/params</i> <i>/all</i> <i>/httpConfiguration</i> <i>/configuration</i> <i>/server</i> <i>/servers</i> <i>/settings</i> +---+</p></section><section>
-<h4><a name="Ignoring_Cookies"></a>Ignoring Cookies</h4>
+<h4>Ignoring Cookies</h4>
<p>Like the example above, telling the HttpClient to ignore cookies for all methods of request is a simple matter of configuring the <code>http.protocol.cookie-policy</code> parameter (it uses a regular string value, so no special syntax is required):</p>
<div class="source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -405,9 +405,9 @@ problems with HTTP servers and proxies t
</servers>
</settings></pre></div>
<p>The configuration above can be useful in cases where the repository is using cookies - like the session cookies that are often mistakenly turned on or left on in appservers - alongside HTTP redirection. In these cases, it becomes far more likely that the cookie issued by the appserver uses a <code>Path</code> that is inconsistent with the one used by the client to access the server. If you have this problem, and know that you don't need to use this session cookie, you can ignore cookies from this server with the above configuration.</p></section></section><section>
-<h3><a name="Support_for_General-Wagon_Configuration_Standards"></a>Support for General-Wagon Configuration Standards</h3>
+<h3>Support for General-Wagon Configuration Standards</h3>
<p>It should be noted that configuration options previously available in the HttpClient-driven HTTP wagon are still supported in addition to this new, fine-grained approach. These include the configuration of HTTP headers and connection timeouts. Let's examine each of these briefly:</p><section>
-<h4><a name="HTTP_Headers"></a>HTTP Headers</h4>
+<h4>HTTP Headers</h4>
<p>In all HTTP Wagon implementations, you can add your own HTTP headers like this:</p>
<div class="source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -425,7 +425,7 @@ problems with HTTP servers and proxies t
</servers>
</settings></pre></div>
<p>It's important to understand that the above approach doesn't allow you to turn off all of the default HTTP headers; nor does it allow you to specify headers on a per-method basis. However, this configuration remains available in both the lightweight and httpclient-based Wagon implementations.</p></section><section>
-<h4><a name="Connection_Timeouts"></a>Connection Timeouts</h4>
+<h4>Connection Timeouts</h4>
<p>All wagon implementations that extend the <code>AbstractWagon</code> class, including those for SCP, HTTP, FTP, and more, allow the configuration of a connection timeout, to allow the user to tell Maven how long to wait before giving up on a connection that has not responded. This option is preserved in the HttpClient-based wagon, but this wagon also provides a fine-grained alternative configuration that can allow you to specify timeouts per-method for a given server. The old configuration option - which is still supported - looks like this:</p>
<div class="source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -453,7 +453,7 @@ problems with HTTP servers and proxies t
</servers>
</settings></pre></div>
<p>If all you need is a per-server timeout configuration, you still have the option to use the old <code><timeout></code> parameter. If you need to separate timeout preferences according to HTTP method, you can use one more like that specified directly above.</p></section><section>
-<h4><a name="Read_time_out"></a>Read time out</h4>
+<h4>Read time out</h4>
<p>With Wagon 2.0 and Apache Maven 3.0.4, a default timeout of 30 minutes comes by default. If you want to change this value, you can add the following setup in your settings:</p>
<div class="source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -469,7 +469,7 @@ problems with HTTP servers and proxies t
</server>
</servers>
</settings></pre></div></section></section><section>
-<h3><a name="Resources"></a>Resources</h3>
+<h3>Resources</h3>
<ol style="list-style-type: decimal">
<li><a class="externalLink" href="https://hc.apache.org/httpcomponents-client-4.5.x/">HttpClient website</a></li>
<li><a class="externalLink" href="https://hc.apache.org/httpclient-3.x/preference-api.html">HttpClient preference architecture and configuration guide</a></li>
Modified: maven/website/content/guides/mini/guide-large-scale-centralized-deployments.html
==============================================================================
--- maven/website/content/guides/mini/guide-large-scale-centralized-deployments.html (original)
+++ maven/website/content/guides/mini/guide-large-scale-centralized-deployments.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-large-scale-centralized-deployments.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-large-scale-centralized-deployments.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="Phil Clay" />
<meta name="date" content="2021-01-01" />
<title>Maven – Guide to Large Scale Centralized Deployments</title>
@@ -153,7 +153,7 @@
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Guide_to_Large_Scale_Centralized_Deployments"></a>Guide to Large Scale Centralized Deployments</h1>
+<h1>Guide to Large Scale Centralized Deployments</h1>
<p>This guide covers a simple optimized approach to using a <a href="../../repository-management.html">repository manager</a> in a large organization with hundreds/thousands of Maven projects.</p>
<p>The pillars of this approach are:</p>
<ol style="list-style-type: decimal">
@@ -163,7 +163,7 @@
<li>Maven clients should upload proprietary artifacts to the repository manager.</li></ul></li>
<li>Configure the location to download/upload artifacts in Maven <code>settings.xml</code> files, rather than in <code>pom.xml</code> files.</li>
<li>Centrally manage the <code>settings.xml</code> files, and distribute them via automation.</li></ol><section>
-<h2><a name="Repository_Manager_Layout">Repository Manager Layout</a></h2>
+<h2><a id="Repository_Manager_Layout">Repository Manager Layout</a></h2>
<p>Repository managers generally have at least three types of repositories:</p>
<dl>
<dt>hosted</dt>
@@ -183,7 +183,7 @@
<ul>
<li><a href="#Managing_Downloads_from_the_Repository_Manager">Download</a> artifacts from the virtual repository.</li>
<li><a href="#Managing_Uploads_to_the_Repository_Manager">Upload</a> artifacts to one of the hosted repositories.</li></ul></section><section>
-<h2><a name="Managing_Downloads_from_the_Repository_Manager">Managing Downloads from the Repository Manager</a></h2>
+<h2><a id="Managing_Downloads_from_the_Repository_Manager">Managing Downloads from the Repository Manager</a></h2>
<p>All artifacts used by Maven projects in the organization should be downloaded from the single virtual repository of the repository manager.</p>
<p>Maven can be instructed to download artifacts from the repository manager's virtual repository by defining a mirror in the Maven <code>settings.xml</code> file as described in the <a href="./guide-mirror-settings.html">Guide to Mirror Settings</a>.</p>
<p>Example: To download artifacts from the corporate repository manager's <code>maven-virtual</code> repository:</p>
@@ -200,7 +200,7 @@
</mirrors>
...
</settings></pre></div></section><section>
-<h2><a name="Managing_Uploads_to_the_Repository_Manager">Managing Uploads to the Repository Manager</a></h2>
+<h2><a id="Managing_Uploads_to_the_Repository_Manager">Managing Uploads to the Repository Manager</a></h2>
<p>All proprietary artifacts produced by Maven projects in the organization should be uploaded to the repository manager's hosted repositories.</p>
<p>The <a href="../../plugins/maven-deploy-plugin">Maven Deploy Plugin</a> can be instructed to upload artifacts to the repository manager's repositories by defining the <code>alt*DeploymentRepository</code> properties in the Maven <code>settings.xml</code> file. When these properties are defined, the Maven Deploy Plugin's <a href="../../plugins/maven-deploy-plugin/deploy-mojo.html">deploy</a> goal uses them instead of the <code><distributionManagement></code> section of <code>pom.xml</code> files to determine where to upload artifacts.</p>
<p>Defining the upload destination of artifacts in <code>settings.xml</code> files rather than in the <code><distributionManagement></code> section of <code>pom.xml</code> files allows the destinations to be centrally managed, which simplifies maintenance if the destinations need to change. In other words, rather than changing a huge number of <code>pom.xml</code> files, you just need to change <a href="#Settings_File_Locations">relatively few</a> <code>settings.xml</code> files if/when the distribution locations need to change.</p>
@@ -283,7 +283,7 @@
</activeProfiles>
...
</settings></pre></div></section><section>
-<h2><a name="Settings_File_Locations">Settings File Locations</a></h2>
+<h2><a id="Settings_File_Locations">Settings File Locations</a></h2>
<p>Maven <code>settings.xml</code> files need to be available wherever Maven builds are performed, typically:</p>
<ul>
<li>on continuous integration servers, and</li>
Modified: maven/website/content/guides/mini/guide-manifest.html
==============================================================================
--- maven/website/content/guides/mini/guide-manifest.html (original)
+++ maven/website/content/guides/mini/guide-manifest.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-manifest.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-manifest.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="Jason van Zyl
Dennis Lundberg" />
<meta name="date" content="2010-08-19" />
@@ -156,7 +156,7 @@ Dennis Lundberg" />
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Guide_to_Working_with_Manifests"></a>Guide to Working with Manifests</h1>
+<h1>Guide to Working with Manifests</h1>
<p>In order to modify the manifest of the archive produced by the packaging plug-ins you need to create a configuration for it. The definitive guide for this is <a href="/shared/maven-archiver/index.html">the site for the Maven Archiver shared component</a>. This component is used by all our packaging plugins.</p></section>
</main>
</div>
Modified: maven/website/content/guides/mini/guide-maven-classloading.html
==============================================================================
--- maven/website/content/guides/mini/guide-maven-classloading.html (original)
+++ maven/website/content/guides/mini/guide-maven-classloading.html Wed Feb 8 20:32:12 2023
@@ -2,14 +2,14 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M3 from content/apt/guides/mini/guide-maven-classloading.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-maven-classloading.apt at 2023-02-08
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<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-M3" />
+ <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" />
<meta name="author" content="Jason van Zyl
Anders Kristian Andersen
Konrad Windszus" />
@@ -157,7 +157,7 @@ Konrad Windszus" />
</header>
<main id="bodyColumn" class="span10" >
<section>
-<h1><a name="Guide_to_Maven_Classloading"></a>Guide to Maven Classloading</h1>
+<h1>Guide to Maven Classloading</h1>
<p>This is a description of the classloader hierarchy in Maven.</p>
<ul>
<li><a href="#Overview">Overview</a></li>
@@ -169,7 +169,7 @@ Konrad Windszus" />
<li><a href="#Project_Classloaders">Project Classloaders</a></li>
<li><a href="#Plugin_Classloaders">Plugin Classloaders</a></li>
<li><a href="#Custom_Classloaders">Custom Classloaders</a></li></ul><section>
-<h2><a name="Overview"></a>Overview</h2>
+<h2>Overview</h2>
<p>Maven uses the <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-classworlds/">Plexus Classworlds</a> classloading framework to create the classloader graph. If you look in your <code>${maven.home}/boot</code> directory, you will see a single JAR which is the Classworlds JAR we use to boot the classloader graph. The Classworlds JAR is the only element of the Java <code>CLASSPATH</code>. The other classloaders are built by Classworlds ("realms" in Classworlds terminology).</p>
<p>Each realm exposes</p>
<ol style="list-style-type: decimal">
@@ -177,21 +177,21 @@ Konrad Windszus" />
<li>optionally some classes from a directory or JAR</li>
<li>one parent classloader</li></ol>
<p>The search order is always as given above.</p></section><section>
-<h2><a name="Platform_Classloader">Platform Classloader</a></h2>
+<h2><a id="Platform_Classloader">Platform Classloader</a></h2>
<p>This is the classloader exposing all JRE classes.</p></section><section>
-<h2><a name="System_Classloader">System Classloader</a></h2>
+<h2><a id="System_Classloader">System Classloader</a></h2>
<p>It contains only Plexus Classworlds and imports the platform classloader.</p></section><section>
-<h2><a name="Core_Classloader">Core Classloader</a></h2>
+<h2><a id="Core_Classloader">Core Classloader</a></h2>
<p>The second classloader down the graph contains the core requirements of Maven. <b>It is used by Maven internally but not by plugins</b>. The core classloader has the libraries in <code>${maven.home}/lib</code>. In general these are just Maven libraries. For example instances of <code><a href="/ref/current/apidocs/org/apache/maven/project/MavenProject.html">MavenProject</a></code> belong to this classloader.</p>
<p>You can add elements to this classloader by <a href="/ref/current/maven-model/maven.html#class_extension">extensions</a>. These are loaded through the same classloader as <code>${maven.home}/lib</code> and hence are available to the Maven core and all plugins for the current project (through the API classloader). More information is available in <a href="./guide-using-extensions.html">Core Extension</a>.</p></section><section>
-<h2><a name="API_Classloader">API Classloader</a></h2>
+<h2><a id="API_Classloader">API Classloader</a></h2>
<p>The API classloader is filtered view of the Core Classloader by exposing only the exported packages from all Core Extensions. The main API is listed in <a class="externalLink" href="https://maven.apache.org/ref/3-LATEST/maven-core/core-extensions.html">Maven Core Extensions Reference</a>.</p>
<p>This has been introduced with Maven 3.3.1 (<a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-5771">MNG-5771</a>).</p></section><section>
-<h2><a name="Build_Extension_Classloaders">Build Extension Classloaders</a></h2><figure><img src="../../buildExtensionClassRealm.svg" alt="" /><figcaption>Build Extension Class Realm</figcaption></figure>
+<h2><a id="Build_Extension_Classloaders">Build Extension Classloaders</a></h2><figure><img src="../../buildExtensionClassRealm.svg" alt="" /><figcaption>Build Extension Class Realm</figcaption></figure>
<p>For every plugin which is marked with <code><extensions>true</extensions></code> or a build extension listed in the according section of the POM, there is a dedicated classloader. Those are isolated. That is, one build extension does not have access to other build extensions. It imports everything from the API classloader. All JSR 330 or Plexus components declared in the underlying JAR are registered as components in the global Plexus container while creating the classloader. In addition all component references in the plugin descriptor are properly wired from the underlying Plexus container. Build extensions have limited effect as they are loaded late.</p></section><section>
-<h2><a name="Project_Classloaders">Project Classloaders</a></h2>
+<h2><a id="Project_Classloaders">Project Classloaders</a></h2>
<p>There is one project classloader per Maven project (identified through its coordinates). This one imports the API Classloader. In addition it exposes all classes from all Build Extension Classloaders which are bound to the current project. This is only released with the container. During the build outside Mojo executions, the thread's context classloader is set to the project classloader.</p></section><section>
-<h2><a name="Plugin_Classloaders">Plugin Classloaders</a></h2><figure><img src="../../pluginClassRealm.svg" alt="" /><figcaption>Plugin Class Realm</figcaption></figure>
+<h2><a id="Plugin_Classloaders">Plugin Classloaders</a></h2><figure><img src="../../pluginClassRealm.svg" alt="" /><figcaption>Plugin Class Realm</figcaption></figure>
<p>Each plugin (which is not marked as build extension) has its own classloader that imports the Project classloader. </p>
<p>Plugins marked with <code><extensions>true</extensions></code> leverage the Build Extension classloader instead of the Plugin classloader.</p>
<p>Users can add dependencies to this classloader by adding dependencies to a plugin in the <code><a href="/ref/current/maven-model/maven.html#class_plugin">plugins/plugin</a></code> section of their project <code>pom.xml</code>. Here is a sample of adding <code>ant-nodeps</code> to the plugin classloader of the Antrun Plugin and hereby enabling the use of additional/optional Ant tasks:</p>
@@ -211,7 +211,7 @@ Konrad Windszus" />
<p>Plugins can inspect their effective runtime class path via the expressions <code>${plugin.artifacts}</code> or <code>${plugin.artifactMap}</code> to have a list or map, respectively, of resolved artifacts injected from the <code><a href="/ref/current/maven-plugin-api/apidocs/org/apache/maven/plugin/descriptor/PluginDescriptor.html">PluginDescriptor</a></code>.</p>
<p>Please note that the plugin classloader does neither contain the <a href="/ref/current/maven-model/maven.html#class_dependency">dependencies</a> of the current project nor its build output. Instead, plugins can query the project's compile, runtime and test class path from the <code><a href="/ref/current/apidocs/org/apache/maven/project/MavenProject.html">MavenProject</a></code> in combination with the mojo annotation <code>requiresDependencyResolution</code> from the <a href="/developers/mojo-api-specification.html">Mojo API Specification</a>. For instance, flagging a mojo with <code>@requiresDependencyResolution runtime</code> enables it to query the runtime class path of the current project from which it could create further classloaders.</p>
<p>When a build plugin is executed, the thread's context classloader is set to the plugin classloader.</p></section><section>
-<h2><a name="Custom_Classloaders">Custom Classloaders</a></h2>
+<h2><a id="Custom_Classloaders">Custom Classloaders</a></h2>
<p>Plugins are free to create further classloaders. For example, a plugin might want to create a classloader that combines the plugin class path and the project class path.</p>
<p>It is important to understand that the plugin classloader cannot load classes from any of those custom classloaders. Some factory patterns require that. Here you must add the classes to the plugin classloader as shown before.</p></section></section>
</main>