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 2022/06/02 06:45:00 UTC
svn commit: r1901539 - in /maven/website/content: apache-maven.pdf guides/introduction/introduction-to-optional-and-excludes-dependencies.html maven-site-1.0-site.jar
Author: svn-site-role
Date: Thu Jun 2 06:45:00 2022
New Revision: 1901539
Log:
Site checkin for project Apache Maven Site
Modified:
maven/website/content/apache-maven.pdf
maven/website/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html
maven/website/content/maven-site-1.0-site.jar
Modified: maven/website/content/apache-maven.pdf
==============================================================================
Binary files - no diff available.
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 Thu Jun 2 06:45:00 2022
@@ -165,7 +165,7 @@
<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></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>
+<p>A dependency is declared optional by setting the <code><optional></code> element to true in its dependency declaration:</p>
<div class="source"><pre class="prettyprint linenums">
<project>
...
@@ -182,11 +182,13 @@
</project>
</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">
+<div>
+<pre>
Project-A -> Project-B
</pre></div>
<p>The diagram above says that Project-A depends on Project-B. When A declares B as an optional dependency in its POM, this relationship remains unchanged. It's just like a normal build where Project-B will be added in Project-A's classpath.</p>
-<div class="source"><pre class="prettyprint linenums">
+<div>
+<pre>
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></section><section>
@@ -195,7 +197,7 @@ Project-X -> Project-A
<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 exclude 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>
+<p>Add an <code><exclusions></code> element in the <code><dependency></code> element by which the problematic jar is included.</p>
<div class="source"><pre class="prettyprint linenums">
<project>
...
@@ -216,7 +218,8 @@ Project-X -> Project-A
</project>
</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">
+<div>
+<pre>
Project-A
-> Project-B
-> Project-D <! -- This dependency should be excluded -->
@@ -225,8 +228,9 @@ Project-A
-> Project C
</pre></div>
<p>The diagram shows that Project-A depends on both Project-B and C. Project-B depends on Project-D. Project-D depends on both Project-E and F. By default, Project A's classpath will include:</p>
-<div class="source"><pre class="prettyprint linenums">B, C, D, E, F</pre></div>
-<p>Suppose you don't want project D and its dependencies to be added to Project A's classpath because some of Project-D's dependencies are missing from the repository, and you don't need the functionality in Project-B that depends on Project-D anyway. Project-B's developers could have marked the dependency on Project-D <optional>true</optional>:</p>
+<div>
+<pre>B, C, D, E, F</pre></div>
+<p>Suppose you don't want project D and its dependencies to be added to Project A's classpath because some of Project-D's dependencies are missing from the repository, and you don't need the functionality in Project-B that depends on Project-D anyway. Project-B's developers could have marked the dependency on Project-D <code><optional>true</optional></code>:</p>
<div class="source"><pre class="prettyprint linenums"><dependency>
<groupId>sample.ProjectD</groupId>
<artifactId>ProjectD</artifactId>
@@ -258,12 +262,14 @@ Project-A
</project>
</pre></div>
<p>If you deploy Project-A to a repository, and Project-X declares a normal dependency on Project-A, will Project-D still be excluded from the classpath?</p>
-<div class="source"><pre class="prettyprint linenums">
+<div>
+<pre>
Project-X -> Project-A
</pre></div>
<p>The answer is <b>Yes</b>. Project-A has declared that it doesn't need Project-D to run, so it won't be brought in as a transitive dependency of Project-A. </p>
<p>Now, consider that Project-X depends on Project-Y, as in the diagram below:</p>
-<div class="source"><pre class="prettyprint linenums">
+<div>
+<pre>
Project-X -> Project-Y
-> Project-B
-> Project-D
@@ -271,7 +277,8 @@ Project-X -> Project-Y
</pre></div>
<p>Project-Y also has a dependency on Project-B, and it does need the features supported by Project-D. Therefore, it will NOT place an exclusion on Project-D in its dependency list. It may also supply an additional repository, from which it can resolve Project-E. In this case, it's important that Project-D <b>is not</b> excluded globally, since it is a legitimate dependency of Project-Y. </p>
<p>As another scenario, suppose the dependency you don't want is Project-E instead of Project-D. How do you exclude it? See the diagram below:</p>
-<div class="source"><pre class="prettyprint linenums">
+<div>
+<pre>
Project-A
-> Project-B
-> Project-D
@@ -305,7 +312,7 @@ Project-A
</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 <a class="externalLink" href="https://maven.apache.org/enforcer/enforcer-rules/bannedDependencies.html">banned dependencies rule</a> 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>
+<p>If you truly want to ensure that a particular dependency appears nowhere in your classpath, regardless of path, the <a href="/enforcer/enforcer-rules/bannedDependencies.html">banned dependencies rule</a> 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>
</main>
</div>
</div>
Modified: maven/website/content/maven-site-1.0-site.jar
==============================================================================
Binary files - no diff available.