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 2019/06/09 13:59:37 UTC
svn commit: r1860906 [9/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/ doc...
Modified: maven/website/content/guides/introduction/introduction-to-archetypes.html
==============================================================================
--- maven/website/content/guides/introduction/introduction-to-archetypes.html (original)
+++ maven/website/content/guides/introduction/introduction-to-archetypes.html Sun Jun 9 13:59:34 2019
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from content/apt/guides/introduction/introduction-to-archetypes.apt at 2019-06-09
+ | Generated by Apache Maven Doxia Site Renderer 1.9 from content/apt/guides/introduction/introduction-to-archetypes.apt at 2019-06-09
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
@@ -139,19 +139,16 @@
</div>
</div>
<div id="bodyColumn" class="span10" >
-<div class="section">
-<h2><a name="Introduction_to_Archetypes"></a>Introduction to Archetypes</h2></div>
-<div class="section">
+<section>
+<h2><a name="Introduction_to_Archetypes"></a>Introduction to Archetypes</h2></section><section>
<h2><a name="What_is_Archetype.3F"></a>What is Archetype?</h2>
<p>In short, Archetype is a Maven project templating toolkit. An archetype is defined as <i>an original pattern or model from which all other things of the same kind are made</i>. The name fits as we are trying to provide a system that provides a consistent means of generating Maven projects. Archetype will help authors create Maven project templates for users, and provides users with the means to generate parameterized versions of those project templates.</p>
<p>Using archetypes provides a great way to enable developers quickly in a way consistent with best practices employed by your project or organization. Within the Maven project, we use archetypes to try and get our users up and running as quickly as possible by providing a sample project that demonstrates many of the features of Maven, while introducing new users to the best practices employed by Maven. In a matter of seconds, a new user can have a working Maven project to use as a jumping board for investigating more of the features in Maven. We have also tried to make the Archetype mechanism additive, and by that we mean allowing portions of a project to be captured in an archetype so that pieces or aspects of a project can be added to existing projects. A good example of this is the Maven site archetype. If, for example, you have used the quick start archetype to generate a working project, you can then quickly create a site for that project by using the site archetype within tha
t existing project. You can do anything like this with archetypes.</p>
-<p>You may want to standardize J2EE development within your organization, so you may want to provide archetypes for EJBs, or WARs, or for your web services. Once these archetypes are created and deployed in your organization's repository, they are available for use by all developers within your organization.</p>
-<div class="section">
+<p>You may want to standardize J2EE development within your organization, so you may want to provide archetypes for EJBs, or WARs, or for your web services. Once these archetypes are created and deployed in your organization's repository, they are available for use by all developers within your organization.</p><section>
<h3><a name="Using_an_Archetype"></a>Using an Archetype</h3>
-<p>To create a new project based on an Archetype, you need to call <tt>mvn archetype:generate</tt> goal, like the following:</p>
+<p>To create a new project based on an Archetype, you need to call <code>mvn archetype:generate</code> goal, like the following:</p>
<div class="source"><pre class="prettyprint linenums">mvn archetype:generate</pre></div>
-<p>Please refer to <a href="/archetype/maven-archetype-plugin/usage.html">Archetype Plugin page</a>.</p></div>
-<div class="section">
+<p>Please refer to <a href="/archetype/maven-archetype-plugin/usage.html">Archetype Plugin page</a>.</p></section><section>
<h3><a name="Provided_Archetypes"></a>Provided Archetypes</h3>
<p>Maven provides several Archetype artifacts:</p>
<table border="1" class="table table-striped">
@@ -191,10 +188,9 @@
<tr class="b">
<td align="left">maven-archetype-webapp</td>
<td align="left">An archetype to generate a sample Maven Webapp project.</td></tr></table>
-<p>For more information on these archetypes, please refer to the <a href="/archetypes/index.html">Maven Archetype Bundles page</a>.</p></div>
-<div class="section">
+<p>For more information on these archetypes, please refer to the <a href="/archetypes/index.html">Maven Archetype Bundles page</a>.</p></section><section>
<h3><a name="What_makes_up_an_Archetype.3F"></a>What makes up an Archetype?</h3>
-<p>Archetypes are packaged up in a JAR and they consist of the archetype metadata which describes the contents of archetype, and a set of <a class="externalLink" href="http://velocity.apache.org/">Velocity</a> templates which make up the prototype project. If you would like to know how to make your own archetypes, please refer to our <a href="../mini/guide-creating-archetypes.html">Guide to creating archetypes</a>.</p></div></div>
+<p>Archetypes are packaged up in a JAR and they consist of the archetype metadata which describes the contents of archetype, and a set of <a class="externalLink" href="http://velocity.apache.org/">Velocity</a> templates which make up the prototype project. If you would like to know how to make your own archetypes, please refer to our <a href="../mini/guide-creating-archetypes.html">Guide to creating archetypes</a>.</p></section></section>
</div>
</div>
</div>
Modified: maven/website/content/guides/introduction/introduction-to-dependency-mechanism.html
==============================================================================
--- maven/website/content/guides/introduction/introduction-to-dependency-mechanism.html (original)
+++ maven/website/content/guides/introduction/introduction-to-dependency-mechanism.html Sun Jun 9 13:59:34 2019
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from content/apt/guides/introduction/introduction-to-dependency-mechanism.apt at 2019-06-09
+ | Generated by Apache Maven Doxia Site Renderer 1.9 from content/apt/guides/introduction/introduction-to-dependency-mechanism.apt at 2019-06-09
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
@@ -149,7 +149,7 @@ Karl Heinz Marbaise" />
</div>
</div>
<div id="bodyColumn" class="span10" >
-<div class="section">
+<section>
<h2><a name="Introduction_to_the_Dependency_Mechanism"></a>Introduction to the Dependency Mechanism</h2>
<p>Dependency management is a core feature of Maven. Managing dependencies for a single project is easy. Managing dependencies for multi-module projects and applications that consist of hundreds of modules is possible. Maven helps a great deal in defining, creating, and maintaining reproducible builds with well-defined classpaths and library versions.</p>
<p>Learn more about:</p>
@@ -161,8 +161,7 @@ Karl Heinz Marbaise" />
<li><a href="#Dependency_Management">Dependency Management</a>
<ul>
<li><a href="#Importing_Dependencies">Importing Dependencies</a></li></ul></li>
-<li><a href="#System_Dependencies">System Dependencies</a></li></ul>
-<div class="section">
+<li><a href="#System_Dependencies">System Dependencies</a></li></ul><section>
<h3><a name="Transitive_Dependencies">Transitive Dependencies</a></h3>
<p>Maven avoids the need to discover and specify the libraries that your own dependencies require by including transitive dependencies automatically.</p>
<p>This feature is facilitated by reading the project files of your dependencies from the remote repositories specified. In general, all dependencies of those projects are used in your project, as are any that the project inherits from its parents, or from its dependencies, and so on.</p>
@@ -179,19 +178,18 @@ Karl Heinz Marbaise" />
<p>Although transitive dependencies can implicitly include desired dependencies, it is a good practice to explicitly specify the dependencies you are directly using in your own source code. This best practice proves its value especially when the dependencies of your project changes their dependencies.</p>
<p>For example, assume that your project A specifies a dependency on another project B, and project B specifies a dependency on project C. If you are directly using components in project C, and you don't specify project C in your project A, it may cause build failure when project B suddenly updates/removes its dependency on project C.</p>
<p>Another reason to directly specify dependencies is that it provides better documentation for your project: one can learn more information by just reading the POM file in your project.</p>
-<p>Maven also provides <a href="/plugins/maven-dependency-plugin/analyze-mojo.html">dependency:analyze</a> plugin goal for analyzing the dependencies: it helps making this best practice more achievable.</p></div>
-<div class="section">
+<p>Maven also provides <a href="/plugins/maven-dependency-plugin/analyze-mojo.html">dependency:analyze</a> plugin goal for analyzing the dependencies: it helps making this best practice more achievable.</p></section><section>
<h3><a name="Dependency_Scope">Dependency Scope</a></h3>
<p>Dependency scope is used to limit the transitivity of a dependency, and also to affect the classpath used for various build tasks.</p>
<p>There are 6 scopes available:</p>
<ul>
<li><b>compile</b><br />This is the default scope, used if none is specified. Compile dependencies are available in all classpaths of a project. Furthermore, those dependencies are propagated to dependent projects.</li>
-<li><b>provided</b><br />This is much like <tt>compile</tt>, but indicates you expect the JDK or a container to provide the dependency at runtime. For example, when building a web application for the Java Enterprise Edition, you would set the dependency on the Servlet API and related Java EE APIs to scope <tt>provided</tt> because the web container provides those classes. This scope is only available on the compilation and test classpath, and is not transitive.</li>
+<li><b>provided</b><br />This is much like <code>compile</code>, but indicates you expect the JDK or a container to provide the dependency at runtime. For example, when building a web application for the Java Enterprise Edition, you would set the dependency on the Servlet API and related Java EE APIs to scope <code>provided</code> because the web container provides those classes. This scope is only available on the compilation and test classpath, and is not transitive.</li>
<li><b>runtime</b><br />This scope indicates that the dependency is not required for compilation, but is for execution. It is in the runtime and test classpaths, but not the compile classpath.</li>
<li><b>test</b><br />This scope indicates that the dependency is not required for normal use of the application, and is only available for the test compilation and execution phases. This scope is not transitive.</li>
-<li><b>system</b><br />This scope is similar to <tt>provided</tt> except that you have to provide the JAR which contains it explicitly. The artifact is always available and is not looked up in a repository.</li>
-<li><b>import</b><br />This scope is only supported on a dependency of type <tt>pom</tt> in the <tt><dependencyManagement></tt> section. It indicates the dependency to be replaced with the effective list of dependencies in the specified POM's <tt><dependencyManagement></tt> section. Since they are replaced, dependencies with a scope of <tt>import</tt> do not actually participate in limiting the transitivity of a dependency.</li></ul>
-<p>Each of the scopes (except for <tt>import</tt>) affects transitive dependencies in different ways, as is demonstrated in the table below. If a dependency is set to the scope in the left column, transitive dependencies of that dependency with the scope across the top row will result in a dependency in the main project with the scope listed at the intersection. If no scope is listed, it means the dependency will be omitted.</p>
+<li><b>system</b><br />This scope is similar to <code>provided</code> except that you have to provide the JAR which contains it explicitly. The artifact is always available and is not looked up in a repository.</li>
+<li><b>import</b><br />This scope is only supported on a dependency of type <code>pom</code> in the <code><dependencyManagement></code> section. It indicates the dependency to be replaced with the effective list of dependencies in the specified POM's <code><dependencyManagement></code> section. Since they are replaced, dependencies with a scope of <code>import</code> do not actually participate in limiting the transitivity of a dependency.</li></ul>
+<p>Each of the scopes (except for <code>import</code>) affects transitive dependencies in different ways, as is demonstrated in the table below. If a dependency is set to the scope in the left column, transitive dependencies of that dependency with the scope across the top row will result in a dependency in the main project with the scope listed at the intersection. If no scope is listed, it means the dependency will be omitted.</p>
<table border="1" class="table table-striped">
<tr class="a">
<td align="left"></td>
@@ -223,8 +221,7 @@ Karl Heinz Marbaise" />
<td align="left">-</td>
<td align="left">test</td>
<td align="left">-</td></tr></table>
-<p><b>(*) Note:</b> it is intended that this should be runtime scope instead, so that all compile dependencies must be explicitly listed. However, if a library you depend on extends a class from another library, both must be available at compile time. For this reason, compile time dependencies remain as compile scope even when they are transitive.</p></div>
-<div class="section">
+<p><b>(*) Note:</b> it is intended that this should be runtime scope instead, so that all compile dependencies must be explicitly listed. However, if a library you depend on extends a class from another library, both must be available at compile time. For this reason, compile time dependencies remain as compile scope even when they are transitive.</p></section><section>
<h3><a name="Dependency_Management">Dependency Management</a></h3>
<p>The dependency management section is a mechanism for centralizing dependency information. When you have a set of projects that inherits a common parent it's possible to put all information about the dependency in the common POM and have simpler references to the artifacts in the child POMs. The mechanism is best illustrated through some examples. Given these two POMs which extend the same parent:</p>
<p>Project A:</p>
@@ -353,7 +350,7 @@ Karl Heinz Marbaise" />
</dependencies>
</project>
</pre></div>
-<p><b>NOTE:</b> In two of these dependency references, we had to specify the <type/> element. This is because the minimal set of information for matching a dependency reference against a dependencyManagement section is actually <b>{groupId, artifactId, type, classifier}</b>. In many cases, these dependencies will refer to jar artifacts with no classifier. This allows us to shorthand the identity set to <b>{groupId, artifactId}</b>, since the default for the type field is <tt>jar</tt>, and the default classifier is null.</p>
+<p><b>NOTE:</b> In two of these dependency references, we had to specify the <type/> element. This is because the minimal set of information for matching a dependency reference against a dependencyManagement section is actually <b>{groupId, artifactId, type, classifier}</b>. In many cases, these dependencies will refer to jar artifacts with no classifier. This allows us to shorthand the identity set to <b>{groupId, artifactId}</b>, since the default for the type field is <code>jar</code>, and the default classifier is null.</p>
<p>A second, and very important use of the dependency management section is to control the versions of artifacts used in transitive dependencies. As an example consider these projects:</p>
<p>Project A:</p>
<div class="source"><pre class="prettyprint linenums">
@@ -437,8 +434,7 @@ Karl Heinz Marbaise" />
<li>a and c both are declared as dependencies of the project so version 1.0 is used due to dependency mediation. Both also have runtime scope since it is directly specified.</li>
<li>b is defined in B's parent's dependency management section and since dependency management takes precedence over dependency mediation for transitive dependencies, version 1.0 will be selected should it be referenced in a or c's pom. b will also have compile scope.</li>
<li>Finally, since d is specified in B's dependency management section, should d be a dependency (or transitive dependency) of a or c, version 1.0 will be chosen - again because dependency management takes precedence over dependency mediation and also because the current pom's declaration takes precedence over its parent's declaration.</li></ul>
-<p>The reference information about the dependency management tags is available from the <a href="../../ref/current/maven-model/maven.html#class_DependencyManagement">project descriptor reference</a>.</p>
-<div class="section">
+<p>The reference information about the dependency management tags is available from the <a href="../../ref/current/maven-model/maven.html#class_DependencyManagement">project descriptor reference</a>.</p><section>
<h4><a name="Importing_Dependencies">Importing Dependencies</a></h4>
<p>The examples in the previous section describe how to specify managed dependencies through inheritance. However, in larger projects it may be impossible to accomplish this since a project can only inherit from a single parent. To accommodate this, projects can import managed dependencies from other projects. This is accomplished by declaring a pom artifact as a dependency with a scope of "import".</p>
<p>Project B:</p>
@@ -721,10 +717,9 @@ Karl Heinz Marbaise" />
<ul>
<li>Do not attempt to import a pom that is defined in a submodule of the current pom. Attempting to do that will result in the build failing since it won't be able to locate the pom.</li>
<li>Never declare the pom importing a pom as the parent (or grandparent, etc) of the target pom. There is no way to resolve the circularity and an exception will be thrown.</li>
-<li>When referring to artifacts whose poms have transitive dependencies the project will need to specify versions of those artifacts as managed dependencies. Not doing so will result in a build failure since the artifact may not have a version specified. (This should be considered a best practice in any case as it keeps the versions of artifacts from changing from one build to the next).</li></ul></div></div>
-<div class="section">
+<li>When referring to artifacts whose poms have transitive dependencies the project will need to specify versions of those artifacts as managed dependencies. Not doing so will result in a build failure since the artifact may not have a version specified. (This should be considered a best practice in any case as it keeps the versions of artifacts from changing from one build to the next).</li></ul></section></section><section>
<h3><a name="System_Dependencies">System Dependencies</a></h3>
-<p><tt>Important note: This is deprecated.</tt></p>
+<p><code>Important note: This is deprecated.</code></p>
<p>Dependencies with the scope <i>system</i> are always available and are not looked up in repository. They are usually used to tell Maven about dependencies which are provided by the JDK or the VM. Thus, system dependencies are especially useful for resolving dependencies on artifacts which are now provided by the JDK, but where available as separate downloads earlier. Typical example are the JDBC standard extensions or the Java Authentication and Authorization Service (JAAS).</p>
<p>A simple example would be:</p>
<div class="source"><pre class="prettyprint linenums">
@@ -742,7 +737,7 @@ Karl Heinz Marbaise" />
...
</project>
</pre></div>
-<p>If your artifact is provided by the JDK's <tt>tools.jar</tt>, the system path would be defined as follows:</p>
+<p>If your artifact is provided by the JDK's <code>tools.jar</code>, the system path would be defined as follows:</p>
<div class="source"><pre class="prettyprint linenums"><project>
...
<dependencies>
@@ -755,7 +750,7 @@ Karl Heinz Marbaise" />
</dependency>
</dependencies>
...
-</project></pre></div></div></div>
+</project></pre></div></section></section>
</div>
</div>
</div>
Modified: maven/website/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html
==============================================================================
--- maven/website/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html (original)
+++ maven/website/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html Sun Jun 9 13:59:34 2019
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt at 2019-06-09
+ | Generated by Apache Maven Doxia Site Renderer 1.9 from content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt at 2019-06-09
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
@@ -147,17 +147,14 @@
</div>
</div>
<div id="bodyColumn" class="span10" >
-<div class="section">
+<section>
<h2><a name="Introduction"></a>Introduction</h2>
-<p>This section discusses optional dependencies and dependency exclusions. This will help users to understand what they are and when and how to use them. It also explains why exclusions are made on a per dependency basis instead of at the POM level.</p>
-<div class="section">
+<p>This section discusses optional dependencies and dependency exclusions. This will help users to understand what they are and when and how to use them. It also explains why exclusions are made on a per dependency basis instead of at the POM level.</p><section>
<h3><a name="Optional_Dependencies"></a>Optional Dependencies</h3>
<p>Optional dependencies are used when it's not possible (for whatever reason) to split a project into sub-modules. The idea is that some of the dependencies are only used for certain features in the project and will not be needed if that feature isn't used. Ideally, such a feature would be split into a sub-module that depends on the core functionality project. This new subproject would have only non-optional dependencies, since you'd need them all if you decided to use the subproject's functionality. </p>
-<p>However, since the project cannot be split up (again, for whatever reason), these dependencies are declared optional. If a user wants to use functionality related to an optional dependency, they have to redeclare that optional dependency in their own project. This is not the clearest way to handle this situation, but both optional dependencies and dependency exclusions are stop-gap solutions.</p>
-<div class="section">
+<p>However, since the project cannot be split up (again, for whatever reason), these dependencies are declared optional. If a user wants to use functionality related to an optional dependency, they have to redeclare that optional dependency in their own project. This is not the clearest way to handle this situation, but both optional dependencies and dependency exclusions are stop-gap solutions.</p><section>
<h4><a name="Why_use_optional_dependencies.3F"></a>Why use optional dependencies?</h4>
-<p>Optional dependencies save space and memory. They prevent problematic jars that violate a license agreement or cause classpath issues from being bundled into a WAR, EAR, fat jar, or the like. </p></div>
-<div class="section">
+<p>Optional dependencies save space and memory. They prevent problematic jars that violate a license agreement or cause classpath issues from being bundled into a WAR, EAR, fat jar, or the like. </p></section><section>
<h4><a name="How_do_I_use_the_optional_tag.3F"></a>How do I use the optional tag?</h4>
<p>A dependency is declared optional by setting the <optional> element to true in its dependency declaration:</p>
<div class="source"><pre class="prettyprint linenums">
@@ -174,8 +171,7 @@
</dependency>
</dependencies>
</project>
-</pre></div></div>
-<div class="section">
+</pre></div></section><section>
<h4><a name="How_do_optional_dependencies_work.3F"></a>How do optional dependencies work?</h4>
<div class="source"><pre class="prettyprint linenums">
Project-A -> Project-B
@@ -184,14 +180,11 @@ Project-A -> Project-B
<div class="source"><pre class="prettyprint linenums">
Project-X -> Project-A
</pre></div>
-<p>When another project (Project-X) declares Project-A as a dependency in its POM, the optional nature of the dependency takes effect. Project-B is not included in the classpath of Project-X. You need to declare it directly in the POM of Project X for B to be included in X's classpath.</p></div>
-<div class="section">
+<p>When another project (Project-X) declares Project-A as a dependency in its POM, the optional nature of the dependency takes effect. Project-B is not included in the classpath of Project-X. You need to declare it directly in the POM of Project X for B to be included in X's classpath.</p></section><section>
<h4><a name="Example"></a>Example</h4>
-<p>Suppose there is a project named <i>X2</i> that has similar functionality to <i>Hibernate</i>. It supports many databases such as MySQL, PostgreSQL, and several versions of Oracle. Each supported database requires an additional dependency on a driver jar. All of these dependencies are needed at compile time to build X2. However your project only uses one specific database and doesn't need drivers for the others. X2 can declare these dependencies as optional, so that when your project declares X2 as a direct dependency in its POM, all the drivers supported by the X2 are not automatically included in your project's classpath. Your project will have to include an explicit dependency on the specific driver for the one database it does use.</p></div></div>
-<div class="section">
+<p>Suppose there is a project named <i>X2</i> that has similar functionality to <i>Hibernate</i>. It supports many databases such as MySQL, PostgreSQL, and several versions of Oracle. Each supported database requires an additional dependency on a driver jar. All of these dependencies are needed at compile time to build X2. However your project only uses one specific database and doesn't need drivers for the others. X2 can declare these dependencies as optional, so that when your project declares X2 as a direct dependency in its POM, all the drivers supported by the X2 are not automatically included in your project's classpath. Your project will have to include an explicit dependency on the specific driver for the one database it does use.</p></section></section><section>
<h3><a name="Dependency_Exclusions"></a>Dependency Exclusions</h3>
-<p>Since Maven resolves dependencies transitively, it is possible for unwanted dependencies to be included in your project's classpath. For example, a certain older jar may have security issues or be incompatible with the Java version you're using. To address this, Maven allows you to exlude specific dependencies. Exclusions are set on a specific dependency in your POM, and are targeted at a specific groupId and artifactId. When you build your project, that artifact will not be added to your project's classpath <i>by way of the dependency in which the exclusion was declared</i>.</p>
-<div class="section">
+<p>Since Maven resolves dependencies transitively, it is possible for unwanted dependencies to be included in your project's classpath. For example, a certain older jar may have security issues or be incompatible with the Java version you're using. To address this, Maven allows you to exlude specific dependencies. Exclusions are set on a specific dependency in your POM, and are targeted at a specific groupId and artifactId. When you build your project, that artifact will not be added to your project's classpath <i>by way of the dependency in which the exclusion was declared</i>.</p><section>
<h4><a name="How_to_use_dependency_exclusions"></a>How to use dependency exclusions</h4>
<p>Add an <exclusions> element in the <dependency> element by which the problematic jar is included.</p>
<div class="source"><pre class="prettyprint linenums">
@@ -212,8 +205,7 @@ Project-X -> Project-A
</dependency>
</dependencies>
</project>
-</pre></div></div>
-<div class="section">
+</pre></div></section><section>
<h4><a name="How_dependency_exclusion_works_and_when_to_use_it_.28_as_a_last_resort.21_.29"></a>How dependency exclusion works and when to use it <b>( as a last resort! )</b></h4>
<div class="source"><pre class="prettyprint linenums">
Project-A
@@ -301,11 +293,10 @@ Project-A
</dependency>
</dependencies>
</project>
-</pre></div></div>
-<div class="section">
+</pre></div></section><section>
<h4><a name="Why_exclusions_are_made_on_a_per-dependency_basis.2C_rather_than_at_the_POM_level"></a>Why exclusions are made on a per-dependency basis, rather than at the POM level</h4>
<p>This is mainly to be sure the dependency graph is predictable, and to keep inheritance effects from excluding a dependency that should not be excluded. If you get to the method of last resort and have to put in an exclusion, you should be absolutely certain which of your dependencies is bringing in that unwanted transitive dependency.</p>
-<p>If you truly want to ensure that a particular dependency appears nowhere in your classpath, regardless of path, the [banned dependencies rule](https://maven.apache.org/enforcer/enforcer-rules/bannedDependencies.html) can be configured to fail the build if a problematic dependency is found. When the build fails, you'll need to add specific exclusions on each path the enforcer finds. </p></div></div></div>
+<p>If you truly want to ensure that a particular dependency appears nowhere in your classpath, regardless of path, the [banned dependencies rule](https://maven.apache.org/enforcer/enforcer-rules/bannedDependencies.html) can be configured to fail the build if a problematic dependency is found. When the build fails, you'll need to add specific exclusions on each path the enforcer finds. </p></section></section></section>
</div>
</div>
</div>
Modified: maven/website/content/guides/introduction/introduction-to-plugin-prefix-mapping.html
==============================================================================
--- maven/website/content/guides/introduction/introduction-to-plugin-prefix-mapping.html (original)
+++ maven/website/content/guides/introduction/introduction-to-plugin-prefix-mapping.html Sun Jun 9 13:59:34 2019
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from content/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt at 2019-06-09
+ | Generated by Apache Maven Doxia Site Renderer 1.9 from content/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt at 2019-06-09
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
@@ -139,18 +139,17 @@
</div>
</div>
<div id="bodyColumn" class="span10" >
-<div class="section">
+<section>
<h2><a name="Introduction_to_Plugin_Prefix_Resolution"></a>Introduction to Plugin Prefix Resolution</h2>
<p>When you execute Maven using a standard lifecycle phase, resolving the plugins that participate in that lifecycle is a relatively simple process. However, when you directly invoke a mojo from the command line, as in the case of <b>clean</b>, Maven must have some way of reliably resolving the <b>clean</b> plugin prefix to the <b>maven-clean-plugin</b>. This provides brevity for command-line invocations, while preserving the descriptiveness of the plugin's real artifactId.</p>
<p>To complicate matters even more, not all plugins should be forced to have the same groupId in the repository. Since groupIds are presumed to be controlled by one project, and multiple projects may release plugins for Maven, it follows that plugin-prefix mappings must also accommodate multiple plugin groupIds.</p>
-<p>To address these concerns, Maven provides a new piece of repository-level metadata (not associated with any single artifact) for plugin groups, along with a plugin mapping manager to organize multiple plugin groups and provide search functionality.</p>
-<div class="section">
+<p>To address these concerns, Maven provides a new piece of repository-level metadata (not associated with any single artifact) for plugin groups, along with a plugin mapping manager to organize multiple plugin groups and provide search functionality.</p><section>
<h3><a name="Specifying_a_Plugin.27s_Prefix"></a>Specifying a Plugin's Prefix</h3>
<p>In order to give users a convenient prefix with which to reference your plugin a prefix must be associated with your plugin when it is built. By default, Maven will make a guess at the plugin-prefix to be used, by removing any instances of "maven" or "plugin" surrounded by hyphens in the plugin's artifact ID. The conventional artifact ID formats to use are:</p>
<ul>
-<li><tt>maven-${prefix}-plugin</tt> - for official plugins maintained by the Apache Maven team itself (you <b>must not</b> use this naming pattern for your plugin, see <a href="../plugin/guide-java-plugin-development.html#Plugin_Naming_Convention_and_Apache_Maven_Trademark">this note for more informations</a>)</li>
-<li><tt>${prefix}-maven-plugin</tt> - for plugins from other sources</li></ul>
-<p>If your plugin's artifactId fits this pattern, Maven will automatically map your plugin to the correct prefix in the metadata stored within your plugin's groupId path on the repository. However, if you want to customize the prefix used to reference your plugin, you can specify the prefix directly through a configuration parameter on the <tt>maven-plugin-plugin</tt> in your plugin's POM:</p>
+<li><code>maven-${prefix}-plugin</code> - for official plugins maintained by the Apache Maven team itself (you <b>must not</b> use this naming pattern for your plugin, see <a href="../plugin/guide-java-plugin-development.html#Plugin_Naming_Convention_and_Apache_Maven_Trademark">this note for more informations</a>)</li>
+<li><code>${prefix}-maven-plugin</code> - for plugins from other sources</li></ul>
+<p>If your plugin's artifactId fits this pattern, Maven will automatically map your plugin to the correct prefix in the metadata stored within your plugin's groupId path on the repository. However, if you want to customize the prefix used to reference your plugin, you can specify the prefix directly through a configuration parameter on the <code>maven-plugin-plugin</code> in your plugin's POM:</p>
<div class="source"><pre class="prettyprint linenums"><project>
...
<build>
@@ -169,19 +168,17 @@
</build>
</project></pre></div>
<p>The above configuration will allow users to refer to your plugin by the prefix <b>somePrefix</b>, as in the following example:</p>
-<div class="source"><pre class="prettyprint linenums">mvn somePrefix:goal</pre></div></div>
-<div class="section">
+<div class="source"><pre class="prettyprint linenums">mvn somePrefix:goal</pre></div></section><section>
<h3><a name="Mapping_Prefixes_to_Plugins"></a>Mapping Prefixes to Plugins</h3>
<p>For each groupId configured for searching, Maven will:</p>
<ol style="list-style-type: decimal">
-<li>Download <tt>maven-metadata.xml</tt> from each remote repository into the local repository, and name it <tt>maven-metadata-${repoId}.xml</tt> within the path of ${groupId}.</li>
-<li>Load these metadata files, along with <tt>maven-metadata-local.xml</tt> (if it exists), within the path of ${groupId}. Merge them.</li>
+<li>Download <code>maven-metadata.xml</code> from each remote repository into the local repository, and name it <code>maven-metadata-${repoId}.xml</code> within the path of ${groupId}.</li>
+<li>Load these metadata files, along with <code>maven-metadata-local.xml</code> (if it exists), within the path of ${groupId}. Merge them.</li>
<li>Lookup the plugin prefix in the merged metadata. If it's mapped, it should refer to a concrete groupId-artifactId pair. Otherwise, go on to #1 for the next groupId in the user's plugin-groups.</li></ol>
-<p>These metadata files consist of the <b>groupId</b> it represents (for clarity when the file is opened outside the context of the directory), and a group of <b>plugin</b> elements. Each <b>plugin</b> in this list contains a <b>prefix</b> element denoting the plugin's command-line prefix, and an <b>artifactId</b> element, which provides the other side of the prefix mapping and provides enough information to lookup and use the plugin. When a plugin is installed or deployed, the appropriate metadata file is located - and if the prefix mapping is missing - modified to include the plugin-prefix mapping.</p></div>
-<div class="section">
+<p>These metadata files consist of the <b>groupId</b> it represents (for clarity when the file is opened outside the context of the directory), and a group of <b>plugin</b> elements. Each <b>plugin</b> in this list contains a <b>prefix</b> element denoting the plugin's command-line prefix, and an <b>artifactId</b> element, which provides the other side of the prefix mapping and provides enough information to lookup and use the plugin. When a plugin is installed or deployed, the appropriate metadata file is located - and if the prefix mapping is missing - modified to include the plugin-prefix mapping.</p></section><section>
<h3><a name="Configuring_Maven_to_Search_for_Plugins"></a>Configuring Maven to Search for Plugins</h3>
<p>By default, Maven will search the groupId <b>org.apache.maven.plugins</b> for prefix-to-artifactId mappings for the plugins it needs to perform a given build. However, as previously mentioned, the user may have a need for third-party plugins. Since the Maven project is assumed to have control over the default plugin groupId, this means configuring Maven to search other groupId locations for plugin-prefix mappings.</p>
-<p>As it turns out, this is simple. In the Maven settings file (per-user: <tt>${user.home}/.m2/settings.xml</tt>; global: <tt>${maven.home}/conf/settings.xml</tt>), you can provide a custom <b>pluginGroups</b> section, listing the plugin groupIds you want to search (each groupId goes in its own <b>pluginGroup</b> sub-element). For example, if my project uses a Modello model file, I might have the following in my settings:</p>
+<p>As it turns out, this is simple. In the Maven settings file (per-user: <code>${user.home}/.m2/settings.xml</code>; global: <code>${maven.home}/conf/settings.xml</code>), you can provide a custom <b>pluginGroups</b> section, listing the plugin groupIds you want to search (each groupId goes in its own <b>pluginGroup</b> sub-element). For example, if my project uses a Modello model file, I might have the following in my settings:</p>
<div class="source"><pre class="prettyprint linenums"><pluginGroups>
<pluginGroup>org.codehaus.modello</pluginGroup>
</pluginGroups></pre></div>
@@ -191,11 +188,10 @@
<ul>
<li>org.apache.maven.plugins</li>
<li>org.codehaus.mojo</li></ul>
-<p><b>NOTE:</b> When specifying plugin groups to be used in searching for a prefix mapping, order is critical! By specifying a pluginGroup of <tt>com.myco.plugins</tt> with a prefix of <tt>clean</tt>, I can override the usage of the <tt>maven-clean-plugin</tt> when <tt>clean:clean</tt> is invoked.</p>
-<p><b>NOTE2:</b> For more information on <tt>settings.xml</tt>, see [<a href="#a1">1</a>].</p></div>
-<div class="section">
+<p><b>NOTE:</b> When specifying plugin groups to be used in searching for a prefix mapping, order is critical! By specifying a pluginGroup of <code>com.myco.plugins</code> with a prefix of <code>clean</code>, I can override the usage of the <code>maven-clean-plugin</code> when <code>clean:clean</code> is invoked.</p>
+<p><b>NOTE2:</b> For more information on <code>settings.xml</code>, see [<a href="#a1">1</a>].</p></section><section>
<h3><a name="Resources"></a>Resources</h3>
-<p><a name="a1">1</a> <a href="../mini/guide-configuring-maven.html">Guide to Configuring Maven</a></p></div></div>
+<p><a name="a1">1</a> <a href="../mini/guide-configuring-maven.html">Guide to Configuring Maven</a></p></section></section>
</div>
</div>
</div>
Modified: maven/website/content/guides/introduction/introduction-to-plugins.html
==============================================================================
--- maven/website/content/guides/introduction/introduction-to-plugins.html (original)
+++ maven/website/content/guides/introduction/introduction-to-plugins.html Sun Jun 9 13:59:34 2019
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from content/apt/guides/introduction/introduction-to-plugins.apt at 2019-06-09
+ | Generated by Apache Maven Doxia Site Renderer 1.9 from content/apt/guides/introduction/introduction-to-plugins.apt at 2019-06-09
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
@@ -132,41 +132,33 @@
</div>
</div>
<div id="bodyColumn" class="span10" >
-<div class="section">
+<section>
<h2><a name="Introduction_to_Maven_Plugin_Development"></a>Introduction to Maven Plugin Development</h2>
-<p>Maven consists of a core engine which provides basic project-processing capabilities and build-process management, and a host of plugins which are used to execute the actual build tasks.</p>
-<div class="section">
+<p>Maven consists of a core engine which provides basic project-processing capabilities and build-process management, and a host of plugins which are used to execute the actual build tasks.</p><section>
<h3><a name="What_is_a_Plugin.3F"></a>What is a Plugin?</h3>
<p>"Maven" is really just a core framework for a collection of Maven Plugins. In other words, plugins are where much of the real action is performed, plugins are used to: create jar files, create war files, compile code, unit test code, create project documentation, and on and on. Almost any action that you can think of performing on a project is implemented as a Maven plugin.</p>
<p>Plugins are the central feature of Maven that allow for the reuse of common build logic across multiple projects. They do this by executing an "action" (i.e. creating a WAR file or compiling unit tests) in the context of a project's description - the Project Object Model (POM). Plugin behavior can be customized through a set of unique parameters which are exposed by a description of each plugin goal (or Mojo).</p>
-<p>One of the simplest plugins in Maven is the Clean Plugin. The <a href="../../plugins/maven-clean-plugin/">Maven Clean plugin</a> (maven-clean-plugin) is responsible for removing the target directory of a Maven project. When you run "mvn clean", Maven executes the "clean" goal as defined in the Clean plug-in, and the target directory is removed. The Clean plugin <a href="../../plugins/maven-clean-plugin/clean-mojo.html">defines a parameter</a> which can be used to customize plugin behavior, this parameter is called outputDirectory and it defaults to ${project.build.directory}.</p></div>
-<div class="section">
+<p>One of the simplest plugins in Maven is the Clean Plugin. The <a href="../../plugins/maven-clean-plugin/">Maven Clean plugin</a> (maven-clean-plugin) is responsible for removing the target directory of a Maven project. When you run "mvn clean", Maven executes the "clean" goal as defined in the Clean plug-in, and the target directory is removed. The Clean plugin <a href="../../plugins/maven-clean-plugin/clean-mojo.html">defines a parameter</a> which can be used to customize plugin behavior, this parameter is called outputDirectory and it defaults to ${project.build.directory}.</p></section><section>
<h3><a name="What_is_a_Mojo_.28And_Why_the_H---_is_it_Named_.27Mojo.27.29.3F"></a>What is a Mojo (<i>And Why the H--- is it Named 'Mojo'</i>)?</h3>
<p>A Mojo is really just a goal in Maven, and plug-ins consist of any number of goals (Mojos). Mojos can be defined as annotated Java classes or Beanshell script. A Mojo specifies metadata about a goal: a goal name, which phase of the lifecycle it fits into, and the parameters it is expecting.</p>
<p>Mojo term was introduced in Maven 2 as a complete rework on how to write plugins (see below for more details on Maven 1.x plugins comparison).</p>
-<p>MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for "Plain". Mojo is also an iteresting word (see <a class="externalLink" href="http://www.answers.com/mojo&r=67">definition</a>). From <a class="externalLink" href="http://www.wikipedia.org">Wikipedia</a>, a "mojo" is defined as: "...a small bag worn by a person under the clothes (also known as a mojo hand). Such bags were thought to have supernatural powers, such as protecting from evil, bringing good luck, etc."</p></div>
-<div class="section">
+<p>MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for "Plain". Mojo is also an iteresting word (see <a class="externalLink" href="http://www.answers.com/mojo&r=67">definition</a>). From <a class="externalLink" href="http://www.wikipedia.org">Wikipedia</a>, a "mojo" is defined as: "...a small bag worn by a person under the clothes (also known as a mojo hand). Such bags were thought to have supernatural powers, such as protecting from evil, bringing good luck, etc."</p></section><section>
<h3><a name="What_is_the_Build_Lifecycle.3F_.28Overview.29"></a>What is the Build Lifecycle? (Overview)</h3>
-<p>The build lifecycle is a series of common stages through which all project builds naturally progress. Plugin goals are bound to specific stages in the lifecycle.</p></div></div>
-<div class="section">
+<p>The build lifecycle is a series of common stages through which all project builds naturally progress. Plugin goals are bound to specific stages in the lifecycle.</p></section></section><section>
<h2><a name="Resources"></a>Resources</h2>
<ol style="list-style-type: decimal">
<li><a href="/plugin-developers/index.html">Plugin Development Center</a></li>
-<li><a href="../mini/guide-configuring-plugins.html">Configuring plugins</a></li></ol></div>
-<div class="section">
-<h2><a name="Comparison_to_Maven_1.x_Plugins"></a>Comparison to Maven 1.x Plugins</h2>
-<div class="section">
+<li><a href="../mini/guide-configuring-plugins.html">Configuring plugins</a></li></ol></section><section>
+<h2><a name="Comparison_to_Maven_1.x_Plugins"></a>Comparison to Maven 1.x Plugins</h2><section>
<h3><a name="Similarities_to_Maven_1.x"></a>Similarities to Maven 1.x</h3>
<p>Maven 2.0 is similar to its predecessor in that it has two main functions. First, it organizes project data into a coherent whole, and exposes this data for use within the build process. Second, Maven marshals a set of plugins to do the heavy lifting and execute the actual steps of the build.</p>
<p>Many things in Maven 2 will have at least superficial familiarity to users of Maven 1, and the plugin system is no exception. Maven 2 plugins appear to behave much as their 1.x counterparts do. Like 1.x plugins, they use both project information and custom-defined configurations to perform their work. Also, Maven 2 plugins are organized and executed in a coherent way by the build engine itself - that is to say, the engine is still responsible for organizing and fulfilling a plugin's requirements before executing the plugin itself.</p>
-<p>Operationally, Maven 2.0 should feel very much like a more performant big brother of Maven 1.x. While the POM has definitely changed, it has the same basic layout and features (with notable additions). However, this is where the similarity ends. Maven 2.0 is a complete redesign and reimplementation of the Maven build concept. As such, it has a much different and more evolved architecture - at least to our minds. <b>;-)</b></p></div>
-<div class="section">
+<p>Operationally, Maven 2.0 should feel very much like a more performant big brother of Maven 1.x. While the POM has definitely changed, it has the same basic layout and features (with notable additions). However, this is where the similarity ends. Maven 2.0 is a complete redesign and reimplementation of the Maven build concept. As such, it has a much different and more evolved architecture - at least to our minds. <b>;-)</b></p></section><section>
<h3><a name="Differences_from_Maven_1.x"></a>Differences from Maven 1.x</h3>
<p>However similar the architectures may seem, Maven 2 offers a much richer environment for its plugins than Maven 1 ever did. The new architecture offers a managed lifecycle, multiple implementation languages, reusability outside of the build system, and many more advantages. Arguably the biggest advantage is the ability to write Maven plugins entirely in Java, which allows developers to tap into a rich landscape of development and testing tools to aid in their efforts.</p>
<p>Prior to Maven 2.0, the build system organized relevant plugins into a loosely defined lifecycle, which was determined based on goal prerequisites and decoration via preGoals and postGoals. That experience was critical for the Maven community. It taught us that even though there may be a million different build scenarios out there, most of the activities in those builds fit into just a few broad categories. Moreover, the category to which a goal fits serves as an accurate predictor for where in the build process the goal should execute. Drawing on this experience, Maven 2.0 defines a lifecycle within which plugins are managed according to their relative position within this lifecycle.</p>
<p>Starting with Maven 2.0, plugins implemented in different programming or scripting languages can coexist within the same build process. This removes the requirement that plugin developers learn a particular scripting language in order to interact with Maven. It also reduced the risk associated with the stability or richness of any particular scripting language.</p>
-<p>Also starting with Maven 2.0 is an effort to integrate multiproject builds directly into the core architecture. In Maven 1.x, many large projects were fragmented into smaller builds to sidestep issues such as conditional compilation of a subset of classes; separation of client-server code; or cyclical dependencies between distinct application libraries. This in turn created extra complexity with running builds, since multiple builds had to be run in order to build the application as a whole - one or more per project. While the first version (1.x) did indeed address this new multiple projects issue, it did so as an afterthought. The Reactor was created to act as a sort of <i>apply-to-all-these</i> function, and the multiproject plugin was later added to provide Reactor settings for some common build types. However, this solution (it <i>is</i> really only one solution, plus some macros) really never integrated the idea of the multi-project build process into the maven core conceptu
al framework.</p></div>
-<div class="section">
+<p>Also starting with Maven 2.0 is an effort to integrate multiproject builds directly into the core architecture. In Maven 1.x, many large projects were fragmented into smaller builds to sidestep issues such as conditional compilation of a subset of classes; separation of client-server code; or cyclical dependencies between distinct application libraries. This in turn created extra complexity with running builds, since multiple builds had to be run in order to build the application as a whole - one or more per project. While the first version (1.x) did indeed address this new multiple projects issue, it did so as an afterthought. The Reactor was created to act as a sort of <i>apply-to-all-these</i> function, and the multiproject plugin was later added to provide Reactor settings for some common build types. However, this solution (it <i>is</i> really only one solution, plus some macros) really never integrated the idea of the multi-project build process into the maven core conceptu
al framework.</p></section><section>
<h3><a name="Why_Change_the_Plugin_Architecture.3F"></a>Why Change the Plugin Architecture?</h3>
<p>See the previous section for the long version, but the short version can be summed up by the following list of benefits.</p>
<ul>
@@ -175,7 +167,7 @@
<li>Reusability outside of the build system</li>
<li>The ability to write Maven plugins entirely in Java</li></ul>
<p>In Maven 1.0, a plugin was defined using Jelly, and while it was possibly to write a plugin in Java, you still had to wrap your plugin with some obligatory Jelly script. An XML-based scripting language which is interpreted at run-time isn't going to be the best choice for performance, and the development team thought it wise to adopt an approach which would allow plugin developers to choose from an array of plugin implementation choices. The first choice in Maven 2 should be Java plugins, but you may also use one of the supported scripting languages like Beanshell.</p>
-<p>To summarize, the development team saw some critical gaps in the API and architecture of Maven 1.0 plug-ins, and the team decided that addressing these deficiencies was critical to the future progress of Maven from a useful tool to something more robust.</p></div></div>
+<p>To summarize, the development team saw some critical gaps in the API and architecture of Maven 1.0 plug-ins, and the team decided that addressing these deficiencies was critical to the future progress of Maven from a useful tool to something more robust.</p></section></section>
</div>
</div>
</div>