maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r806895 [20/46] - in /websites/staging/maventest/trunk: ./ content/ content/ant/ content/background/ content/css/ content/developers/ content/developers/conventions/ content/developers/release/ content/developers/website/ content/docs/ cont...
Date Thu, 01 Mar 2012 16:35:47 GMT
Added: websites/staging/maventest/trunk/content/guides/introduction/introduction-to-dependency-mechanism.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/introduction/introduction-to-dependency-mechanism.html (added)
+++ websites/staging/maventest/trunk/content/guides/introduction/introduction-to-dependency-mechanism.html Thu Mar  1 16:35:39 2012
@@ -0,0 +1,705 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Introduction to the Dependency Mechanism</title>
+    <style type="text/css" media="all">
+      @import url("../../css/maven-base.css");
+      @import url("../../css/maven-theme.css");
+      @import url("../../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+        <meta name="author" content="Brett Porter
+Trygve Laugstol" />
+        <meta name="Date-Revision-yyyymmdd" content="20120301" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+                                                    
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+                                                        
+<script type="text/javascript">_uacct = "UA-140879-1";
+        urchinTracker();</script>
+                    </head>
+  <body class="composite">
+    <div id="banner">
+                                      <a href="../.././" id="bannerLeft">
+                                                <img src="../../images/apache-maven-project-2.png" alt="" />
+                </a>
+                        <span id="bannerRight">
+                                                <img src="../../images/maven-logo-2.gif" alt="" />
+                </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+            
+                                <div class="xleft">
+                          <a href="http://www.apache.org/" class="externalLink">Apache</a>
+        &gt;
+                  <a href="../../index.html">Maven</a>
+        &gt;
+    Introduction to the Dependency Mechanism
+      </div>
+            <div class="xright">        
+                                 Last Published: 2012-03-01
+            </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+             
+                                                <h5>Main</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../index.html">Welcome</a>
+            </li>
+          </ul>
+                       <h5>Get Maven</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../download.html">Download</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../license.html">License</a>
+            </li>
+          </ul>
+                       <h5>IDE Integration</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../eclipse-plugin.html">Eclipse</a>
+            </li>
+                  <li class="none">
+                  <a href="../../netbeans-module.html">NetBeans</a>
+            </li>
+          </ul>
+                       <h5>About Maven</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../what-is-maven.html">What is Maven?</a>
+            </li>
+                  <li class="none">
+                  <a href="../../maven-features.html">Features</a>
+            </li>
+                  <li class="none">
+                  <a href="../../general.html">FAQ (official)</a>
+            </li>
+                  <li class="none">
+                  <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../powered-by-m2.html">Powered By</a>
+            </li>
+          </ul>
+                       <h5>Documentation</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../plugins/index.html">Maven Plugins</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/index.html">Index (category)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../run-maven/index.html">Running Maven</a>
+            </li>
+                                                                                                                                            <li class="collapsed">
+                  <a href="../../users/index.html">User Centre</a>
+                  </li>
+                                                                                                        <li class="collapsed">
+                  <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+                  </li>
+                  <li class="none">
+                  <a href="../../repository/index.html">Maven Repository Centre</a>
+            </li>
+                  <li class="none">
+                  <a href="../../developers/index.html">Maven Developer Centre</a>
+            </li>
+                  <li class="none">
+                  <a href="../../articles.html">Books and Resources</a>
+            </li>
+                  <li class="none">
+                  <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+            </li>
+          </ul>
+                       <h5>Community</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../community.html">Community Overview</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+            </li>
+                  <li class="none">
+                  <a href="../../users/getting-help.html">Getting Help</a>
+            </li>
+                  <li class="none">
+                  <a href="../../issue-tracking.html">Issue Tracking</a>
+            </li>
+                  <li class="none">
+                  <a href="../../source-repository.html">Source Repository</a>
+            </li>
+                  <li class="none">
+                  <a href="../../team-list.html">The Maven Team</a>
+            </li>
+          </ul>
+                       <h5>Project Documentation</h5>
+                  <ul>
+                                                                                                                          <li class="collapsed">
+                  <a href="../../project-info.html">Project Information</a>
+                  </li>
+          </ul>
+                       <h5>Maven Projects</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../ant-tasks/index.html">Ant Tasks</a>
+            </li>
+                  <li class="none">
+                  <a href="../../archetype/index.html">Archetype</a>
+            </li>
+                  <li class="none">
+                  <a href="../../doxia/index.html">Doxia</a>
+            </li>
+                  <li class="none">
+                  <a href="../../jxr/index.html">JXR</a>
+            </li>
+                  <li class="none">
+                  <a href="../../maven-1.x/index.html">Maven 1.x</a>
+            </li>
+                  <li class="none">
+                  <a href="../../index.html">Maven 2 & 3</a>
+            </li>
+                  <li class="none">
+                  <a href="../../plugins/index.html">Plugins</a>
+            </li>
+                  <li class="none">
+                  <a href="../../scm/index.html">SCM</a>
+            </li>
+                  <li class="none">
+                  <a href="../../shared/index.html">Shared Components</a>
+            </li>
+                  <li class="none">
+                  <a href="../../surefire/index.html">Surefire</a>
+            </li>
+                  <li class="none">
+                  <a href="../../wagon/index.html">Wagon</a>
+            </li>
+          </ul>
+                       <h5>ASF</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+            </li>
+          </ul>
+                                 <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+          <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+        </a>
+                       
+                            </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <div class="section"><h2>Introduction to the Dependency Mechanism<a name="Introduction_to_the_Dependency_Mechanism"></a></h2><p>Dependency management is one of the features of Maven that is best known to users and is one of the areas where Maven excels. There is not much difficulty in managing dependencies for a single a project, but when you start getting into dealing with multi-module projects and applications that consist of tens or hundreds of modules this is where Maven can help you a great deal in maintaining a high degree of control and stability.</p><p>Learn more about:</p><ul><li><a href="#Transitive_Dependencies">Transitive Dependencies</a><ul><li>Excluded/Optional Dependencies</li></ul></li><li><a href="#Dependency_Scope">Dependency Scope</a></li><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"><h3><a name="Transitive_Dependencies">Transitive Dependencies</a></h3><p>Transitive dependencies are a new feature in Maven 2.0. This allows you to avoid needing to discover and specify the libraries that your own dependencies require, and including them 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><p>There is no limit to the number of levels that dependencies can be gathered from, and will only cause a problem if a cyclic dependency is discovered.</p><p>With transitive dependencies, the graph of included libraries can quickly grow quite large. For this reason, there are some additional features that will limit which dependencies are included:</p><ul><li><i>Dependency mediation</i> - this determin
 es what version of a dependency will be used when multiple versions of an artifact are encountered. Currently, Maven 2.0 only supports using the &quot;nearest definition&quot; which means that it will use the version of the closest dependency to your project in the tree of dependencies. You can always guarantee a version by declaring it explicitly in your project's POM. Note that if two dependency versions are at the same depth in the dependency tree, until Maven 2.0.8 it was not defined which one would win, but since Maven 2.0.9 it's the order in the declaration that counts: the first declaration wins.<ul><li>&quot;nearest definition&quot; means that the version used will be the closest one to your project in the tree of dependencies, eg. if dependencies for A, B, and C are defined as A -&gt; B -&gt; C -&gt; D 2.0 and A -&gt; E -&gt; D 1.0, then D 1.0 will be used when building A because the path from A to D through E is shorter. You could explicitly add a dependency to D 2
 .0 in A to force the use of D 2.0</li></ul></li><li><i>Dependency management</i> - this allows project authors to directly specify the versions of artifacts to be used when they are encountered in transitive dependencies or in dependencies where no version has been specified. In the example in the preceding section a dependency was directly added to A even though it is not directly used by A. Instead, A can include D as a dependency in its dependencyManagement section and directly control which version of D is used when, or if, it is ever referenced.</li><li><i>Dependency scope</i> - this allows you to only include dependencies appropriate for the current stage of the build. This is described in more detail below.</li><li><i>Excluded dependencies</i> - If project X depends on project Y, and project Y depends on project Z, the owner of project X can explicitly exclude project Z as a dependency, using the &quot;exclusion&quot; element.</li><li><i>Optional dependencies</i> - If
  project Y depends on project Z, the owner of project Y can mark project Z as an optional dependency, using the &quot;optional&quot; element. When project X depends on project Y, X will depend only on Y and not on Y's optional dependency Z. The owner of project X may then explicitly add a dependency on Z, at her option. (It may be helpful to think of optional dependencies as &quot;excluded by default.&quot;)</li></ul></div><div class="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>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.</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> <i>(only available in Maven 2.0.9 or later)</i><br />This scope is only used on a dependency of type <tt>pom</tt> in the <tt>&lt;dependencyManagement&gt;</tt> section. It indicates that the specified POM should be replaced with the dependencies in that POM's <tt>&lt;dependencyManagement&gt;</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><table border="1" class="bodyTable"><tr class="a"><td align="left"></td><td align="left">compi
 le</td><td align="left">provided</td><td align="left">runtime</td><td align="left">test</td></tr><tr class="b"><td align="left">compile</td><td align="left">compile(*)</td><td align="left">-</td><td align="left">runtime</td><td align="left">-</td></tr><tr class="a"><td align="left">provided</td><td align="left">provided</td><td align="left">-</td><td align="left">provided</td><td align="left">-</td></tr><tr class="b"><td align="left">runtime</td><td align="left">runtime</td><td align="left">-</td><td align="left">runtime</td><td align="left">-</td></tr><tr class="a"><td align="left">test</td><td align="left">test</td><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, there is the case where the library you depend on extends a class from another library, forcing you to have available at compile ti
 me. For this reason, compile time dependencies remain as compile scope even when they are transitive.</p></div><div class="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><div class="source"><pre>
+&lt;project&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;group-a&lt;/groupId&gt;
+      &lt;artifactId&gt;artifact-a&lt;/artifactId&gt;
+      &lt;version&gt;1.0&lt;/version&gt;
+      &lt;exclusions&gt;
+        &lt;exclusion&gt;
+          &lt;groupId&gt;group-c&lt;/groupId&gt;
+          &lt;artifactId&gt;excluded-artifact&lt;/artifactId&gt;
+        &lt;/exclusion&gt;
+      &lt;/exclusions&gt;
+    &lt;/dependency&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;group-a&lt;/groupId&gt;
+      &lt;artifactId&gt;artifact-b&lt;/artifactId&gt;
+      &lt;version&gt;1.0&lt;/version&gt;
+      &lt;type&gt;bar&lt;/type&gt;
+      &lt;scope&gt;runtime&lt;/scope&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><p>Project B:</p><div class="source"><pre>
+&lt;project&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;group-c&lt;/groupId&gt;
+      &lt;artifactId&gt;artifact-b&lt;/artifactId&gt;
+      &lt;version&gt;1.0&lt;/version&gt;
+      &lt;type&gt;war&lt;/type&gt;
+      &lt;scope&gt;runtime&lt;/scope&gt;
+    &lt;/dependency&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;group-a&lt;/groupId&gt;
+      &lt;artifactId&gt;artifact-b&lt;/artifactId&gt;
+      &lt;version&gt;1.0&lt;/version&gt;
+      &lt;type&gt;bar&lt;/type&gt;
+      &lt;scope&gt;runtime&lt;/scope&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><p>These two example POMs share a common dependency and each has one non-trivial dependency. This information can be put in the parent POM like this:</p><div class="source"><pre>
+&lt;project&gt;
+  ...
+  &lt;dependencyManagement&gt;
+    &lt;dependencies&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;group-a&lt;/groupId&gt;
+        &lt;artifactId&gt;artifact-a&lt;/artifactId&gt;
+        &lt;version&gt;1.0&lt;/version&gt;
+
+        &lt;exclusions&gt;
+          &lt;exclusion&gt;
+            &lt;groupId&gt;group-c&lt;/groupId&gt;
+            &lt;artifactId&gt;excluded-artifact&lt;/artifactId&gt;
+          &lt;/exclusion&gt;
+        &lt;/exclusions&gt;
+
+      &lt;/dependency&gt;
+
+      &lt;dependency&gt;
+        &lt;groupId&gt;group-c&lt;/groupId&gt;
+        &lt;artifactId&gt;artifact-b&lt;/artifactId&gt;
+        &lt;version&gt;1.0&lt;/version&gt;
+        &lt;type&gt;war&lt;/type&gt;
+        &lt;scope&gt;runtime&lt;/scope&gt;
+      &lt;/dependency&gt;
+
+      &lt;dependency&gt;
+        &lt;groupId&gt;group-a&lt;/groupId&gt;
+        &lt;artifactId&gt;artifact-b&lt;/artifactId&gt;
+        &lt;version&gt;1.0&lt;/version&gt;
+        &lt;type&gt;bar&lt;/type&gt;
+        &lt;scope&gt;runtime&lt;/scope&gt;
+      &lt;/dependency&gt;
+    &lt;/dependencies&gt;
+  &lt;/dependencyManagement&gt;
+&lt;/project&gt;
+</pre></div><p>And then the two child poms would become much simpler:</p><div class="source"><pre>
+&lt;project&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;group-a&lt;/groupId&gt;
+      &lt;artifactId&gt;artifact-a&lt;/artifactId&gt;
+    &lt;/dependency&gt;
+
+    &lt;dependency&gt;
+      &lt;groupId&gt;group-a&lt;/groupId&gt;
+      &lt;artifactId&gt;artifact-b&lt;/artifactId&gt;
+      &lt;!-- This is not a jar dependency, so we must specify type. --&gt;
+      &lt;type&gt;bar&lt;/type&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><div class="source"><pre>
+&lt;project&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;group-c&lt;/groupId&gt;
+      &lt;artifactId&gt;artifact-b&lt;/artifactId&gt;
+      &lt;!-- This is not a jar dependency, so we must specify type. --&gt;
+      &lt;type&gt;war&lt;/type&gt;
+    &lt;/dependency&gt;
+
+    &lt;dependency&gt;
+      &lt;groupId&gt;group-a&lt;/groupId&gt;
+      &lt;artifactId&gt;artifact-b&lt;/artifactId&gt;
+      &lt;!-- This is not a jar dependency, so we must specify type. --&gt;
+      &lt;type&gt;bar&lt;/type&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><p><b>NOTE:</b> In two of these dependency references, we had to specify the &lt;type/&gt; 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>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>
+&lt;project&gt;
+ &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+ &lt;groupId&gt;maven&lt;/groupId&gt;
+ &lt;artifactId&gt;A&lt;/artifactId&gt;
+ &lt;packaging&gt;pom&lt;/packaging&gt;
+ &lt;name&gt;A&lt;/name&gt;
+ &lt;version&gt;1.0&lt;/version&gt;
+ &lt;dependencyManagement&gt;
+   &lt;dependencies&gt;
+     &lt;dependency&gt;
+       &lt;groupId&gt;test&lt;/groupId&gt;
+       &lt;artifactId&gt;a&lt;/artifactId&gt;
+       &lt;version&gt;1.2&lt;/version&gt;
+     &lt;/dependency&gt;
+     &lt;dependency&gt;
+       &lt;groupId&gt;test&lt;/groupId&gt;
+       &lt;artifactId&gt;b&lt;/artifactId&gt;
+       &lt;version&gt;1.0&lt;/version&gt;
+       &lt;scope&gt;compile&lt;/scope&gt;
+     &lt;/dependency&gt;
+     &lt;dependency&gt;
+       &lt;groupId&gt;test&lt;/groupId&gt;
+       &lt;artifactId&gt;c&lt;/artifactId&gt;
+       &lt;version&gt;1.0&lt;/version&gt;
+       &lt;scope&gt;compile&lt;/scope&gt;
+     &lt;/dependency&gt;
+     &lt;dependency&gt;
+       &lt;groupId&gt;test&lt;/groupId&gt;
+       &lt;artifactId&gt;d&lt;/artifactId&gt;
+       &lt;version&gt;1.2&lt;/version&gt;
+     &lt;/dependency&gt;
+   &lt;/dependencies&gt;
+ &lt;/dependencyManagement&gt;
+&lt;/project&gt;
+</pre></div><p>Project B:</p><div class="source"><pre>
+&lt;project&gt;
+  &lt;parent&gt;
+    &lt;artifactId&gt;A&lt;/artifactId&gt;
+    &lt;groupId&gt;maven&lt;/groupId&gt;
+    &lt;version&gt;1.0&lt;/version&gt;
+  &lt;/parent&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;groupId&gt;maven&lt;/groupId&gt;
+  &lt;artifactId&gt;B&lt;/artifactId&gt;
+  &lt;packaging&gt;pom&lt;/packaging&gt;
+  &lt;name&gt;B&lt;/name&gt;
+  &lt;version&gt;1.0&lt;/version&gt;
+  &lt;dependencyManagement&gt;
+    &lt;dependencies&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;test&lt;/groupId&gt;
+        &lt;artifactId&gt;d&lt;/artifactId&gt;
+        &lt;version&gt;1.0&lt;/version&gt;
+      &lt;/dependency&gt;
+    &lt;/dependencies&gt;
+  &lt;/dependencyManagement&gt;
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;test&lt;/groupId&gt;
+      &lt;artifactId&gt;a&lt;/artifactId&gt;
+      &lt;version&gt;1.0&lt;/version&gt;
+      &lt;scope&gt;runtime&lt;/scope&gt;
+    &lt;/dependency&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;test&lt;/groupId&gt;
+      &lt;artifactId&gt;c&lt;/artifactId&gt;
+      &lt;scope&gt;runtime&lt;/scope&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><p>When maven is run on project B version 1.0 of artifacts a, b, c, and d will be used regardless of the version specified in their pom.</p><ul><li>a and c both are declared as dependencies of the project so version 1.0 is used due to dependency mediation. Both will 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 a
 bout 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"><h4><a name="Importing_Dependencies">Importing Dependencies</a></h4><p><i>The features defined in this section are only available in Maven 2.0.9 or later. This means that poms declaring the import scope will not be parseable by earlier versions of Maven. Weigh this information carefully before deciding to use it. If you do use it, we suggest you use the enforcer plugin to require a minimum Maven version of 2.0.9. We currently do not recommend using this for projects that get deployed to Central.</i></p><p>The examples in the previous section describe how to specify managed dependencies through inheritence. 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 dependenc
 ies from other projects. This is accomplished by declaring a pom artifact as a dependency with a scope of &quot;import&quot;.</p><p>Project B:</p><div class="source"><pre>
+&lt;project&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;groupId&gt;maven&lt;/groupId&gt;
+  &lt;artifactId&gt;B&lt;/artifactId&gt;
+  &lt;packaging&gt;pom&lt;/packaging&gt;
+  &lt;name&gt;B&lt;/name&gt;
+  &lt;version&gt;1.0&lt;/version&gt;
+  &lt;dependencyManagement&gt;
+    &lt;dependencies&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;maven&lt;/groupId&gt;
+        &lt;artifactId&gt;A&lt;/artifactId&gt;
+        &lt;version&gt;1.0&lt;/version&gt;
+        &lt;type&gt;pom&lt;/type&gt;
+        &lt;scope&gt;import&lt;/scope&gt;
+      &lt;/dependency&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;test&lt;/groupId&gt;
+        &lt;artifactId&gt;d&lt;/artifactId&gt;
+        &lt;version&gt;1.0&lt;/version&gt;
+      &lt;/dependency&gt;
+    &lt;/dependencies&gt;
+  &lt;/dependencyManagement&gt;
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;test&lt;/groupId&gt;
+      &lt;artifactId&gt;a&lt;/artifactId&gt;
+      &lt;version&gt;1.0&lt;/version&gt;
+      &lt;scope&gt;runtime&lt;/scope&gt;
+    &lt;/dependency&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;test&lt;/groupId&gt;
+      &lt;artifactId&gt;c&lt;/artifactId&gt;
+      &lt;scope&gt;runtime&lt;/scope&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><p>Assuming A is the pom defined in the preceding example, the end result would be the same. All of A's managed dependencies would be incorporated into B except for d since it is defined in this pom.</p><p>Project X:</p><div class="source"><pre>
+&lt;project&gt;
+ &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+ &lt;groupId&gt;maven&lt;/groupId&gt;
+ &lt;artifactId&gt;X&lt;/artifactId&gt;
+ &lt;packaging&gt;pom&lt;/packaging&gt;
+ &lt;name&gt;X&lt;/name&gt;
+ &lt;version&gt;1.0&lt;/version&gt;
+ &lt;dependencyManagement&gt;
+   &lt;dependencies&gt;
+     &lt;dependency&gt;
+       &lt;groupId&gt;test&lt;/groupId&gt;
+       &lt;artifactId&gt;a&lt;/artifactId&gt;
+       &lt;version&gt;1.1&lt;/version&gt;
+     &lt;/dependency&gt;
+     &lt;dependency&gt;
+       &lt;groupId&gt;test&lt;/groupId&gt;
+       &lt;artifactId&gt;b&lt;/artifactId&gt;
+       &lt;version&gt;1.0&lt;/version&gt;
+       &lt;scope&gt;compile&lt;/scope&gt;
+     &lt;/dependency&gt;
+   &lt;/dependencies&gt;
+ &lt;/dependencyManagement&gt;
+&lt;/project&gt;
+</pre></div><p>Project Y:</p><div class="source"><pre>
+&lt;project&gt;
+ &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+ &lt;groupId&gt;maven&lt;/groupId&gt;
+ &lt;artifactId&gt;Y&lt;/artifactId&gt;
+ &lt;packaging&gt;pom&lt;/packaging&gt;
+ &lt;name&gt;Y&lt;/name&gt;
+ &lt;version&gt;1.0&lt;/version&gt;
+ &lt;dependencyManagement&gt;
+   &lt;dependencies&gt;
+     &lt;dependency&gt;
+       &lt;groupId&gt;test&lt;/groupId&gt;
+       &lt;artifactId&gt;a&lt;/artifactId&gt;
+       &lt;version&gt;1.2&lt;/version&gt;
+     &lt;/dependency&gt;
+     &lt;dependency&gt;
+       &lt;groupId&gt;test&lt;/groupId&gt;
+       &lt;artifactId&gt;c&lt;/artifactId&gt;
+       &lt;version&gt;1.0&lt;/version&gt;
+       &lt;scope&gt;compile&lt;/scope&gt;
+     &lt;/dependency&gt;
+   &lt;/dependencies&gt;
+ &lt;/dependencyManagement&gt;
+&lt;/project&gt;
+</pre></div><p>Project Z:</p><div class="source"><pre>
+&lt;project&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;groupId&gt;maven&lt;/groupId&gt;
+  &lt;artifactId&gt;Z&lt;/artifactId&gt;
+  &lt;packaging&gt;pom&lt;/packaging&gt;
+  &lt;name&gt;Z&lt;/name&gt;
+  &lt;version&gt;1.0&lt;/version&gt;
+  &lt;dependencyManagement&gt;
+    &lt;dependencies&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;maven&lt;/groupId&gt;
+        &lt;artifactId&gt;X&lt;/artifactId&gt;
+        &lt;version&gt;1.0&lt;/version&gt;
+        &lt;type&gt;pom&lt;/type&gt;
+        &lt;scope&gt;import&lt;/scope&gt;
+      &lt;/dependency&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;maven&lt;/groupId&gt;
+        &lt;artifactId&gt;Y&lt;/artifactId&gt;
+        &lt;version&gt;1.0&lt;/version&gt;
+        &lt;type&gt;pom&lt;/type&gt;
+        &lt;scope&gt;import&lt;/scope&gt;
+      &lt;/dependency&gt;
+    &lt;/dependencies&gt;
+  &lt;/dependencyManagement&gt;
+&lt;/project&gt;
+</pre></div><p>In the example above Z imports the managed dependencies from both X and Y. However, both X and Y contain dependency a. Here, version 1.1 of a would be used since X is declared first and a is not declared in Z's dependencyManagement.</p><p>This process is recursive. For example, if X imports another pom, Q, when Z is processed it will simply appear that all of Q's managed dependencies are defined in X.</p><p>Imports are most effective when used for defining a &quot;library&quot; of related artifacts that are generally part of a multiproject build. It is fairly common for one project to use one or more artifacts from these libraries. However, it has sometimes been difficult to keep the versions in the project using the artifacts in synch with the versions distributed in the library. The pattern below illustrates how a &quot;bill of materials&quot; (BOM) can be created for use by other projects.</p><p>The root of the project is the BOM pom. It defines the version
 s of all the artifacts that will be created in the library. Other projects that wish to use the library should import this pom into the dependencyManagement section of their pom.</p><div class="source"><pre>
+&lt;project xmlns=&quot;http://maven.apache.org/POM/4.0.0&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
+    xsi:schemaLocation=&quot;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&quot;&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;groupId&gt;com.test&lt;/groupId&gt;
+  &lt;artifactId&gt;bom&lt;/artifactId&gt;
+  &lt;version&gt;1.0.0&lt;/version&gt;
+  &lt;packaging&gt;pom&lt;/packaging&gt;
+  &lt;properties&gt;
+    &lt;project1Version&gt;1.0.0&lt;/project1Version&gt;
+    &lt;project2Version&gt;1.0.0&lt;/project2Version&gt;
+  &lt;/properties&gt;
+  &lt;dependencyManagement&gt;
+    &lt;dependencies&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;com.test&lt;/groupId&gt;
+        &lt;artifactId&gt;project1&lt;/artifactId&gt;
+        &lt;version&gt;${project1Version}&lt;/version&gt;
+      &lt;/dependency&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;com.test&lt;/groupId&gt;
+        &lt;artifactId&gt;project2&lt;/artifactId&gt;
+        &lt;version&gt;${project1Version}&lt;/version&gt;
+      &lt;/dependency&gt;
+    &lt;/dependencies&gt;
+  &lt;/dependencyManagement&gt;
+  &lt;modules&gt;
+    &lt;module&gt;parent&lt;/module&gt;
+  &lt;/modules&gt;
+&lt;/project&gt;
+</pre></div><p>The parent subproject has the BOM pom as its parent. It is a normal multiproject pom.</p><div class="source"><pre>
+&lt;project xmlns=&quot;http://maven.apache.org/POM/4.0.0&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
+     xsi:schemaLocation=&quot;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&quot;&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;parent&gt;
+    &lt;groupId&gt;com.test&lt;/groupId&gt;
+    &lt;version&gt;1.0.0&lt;/version&gt;
+    &lt;artifactId&gt;bom&lt;/artifactId&gt;
+  &lt;/parent&gt;
+
+  &lt;groupId&gt;com.test&lt;/groupId&gt;
+  &lt;artifactId&gt;parent&lt;/artifactId&gt;
+  &lt;version&gt;1.0.0&lt;/version&gt;
+  &lt;packaging&gt;pom&lt;/packaging&gt;
+
+  &lt;dependencyManagement&gt;
+    &lt;dependencies&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;log4j&lt;/groupId&gt;
+        &lt;artifactId&gt;log4j&lt;/artifactId&gt;
+        &lt;version&gt;1.2.12&lt;/version&gt;
+      &lt;/dependency&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;commons-logging&lt;/groupId&gt;
+        &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
+        &lt;version&gt;1.1.1&lt;/version&gt;
+      &lt;/dependency&gt;
+    &lt;/dependencies&gt;
+  &lt;/dependencyManagement&gt;
+  &lt;modules&gt;
+    &lt;module&gt;project1&lt;/module&gt;
+    &lt;module&gt;project2&lt;/module&gt;
+  &lt;/modules&gt;
+&lt;/project&gt;
+</pre></div><p>Next are the actual project poms.</p><div class="source"><pre>
+&lt;project xmlns=&quot;http://maven.apache.org/POM/4.0.0&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
+     xsi:schemaLocation=&quot;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&quot;&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;parent&gt;
+    &lt;groupId&gt;com.test&lt;/groupId&gt;
+    &lt;version&gt;1.0.0&lt;/version&gt;
+    &lt;artifactId&gt;parent&lt;/artifactId&gt;
+  &lt;/parent&gt;
+  &lt;groupId&gt;com.test&lt;/groupId&gt;
+  &lt;artifactId&gt;project1&lt;/artifactId&gt;
+  &lt;version&gt;${project1Version}&lt;/version&gt;
+  &lt;packaging&gt;jar&lt;/packaging&gt;
+
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;log4j&lt;/groupId&gt;
+      &lt;artifactId&gt;log4j&lt;/artifactId&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+
+&lt;project xmlns=&quot;http://maven.apache.org/POM/4.0.0&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
+     xsi:schemaLocation=&quot;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&quot;&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;parent&gt;
+    &lt;groupId&gt;com.test&lt;/groupId&gt;
+    &lt;version&gt;1.0.0&lt;/version&gt;
+    &lt;artifactId&gt;parent&lt;/artifactId&gt;
+  &lt;/parent&gt;
+  &lt;groupId&gt;com.test&lt;/groupId&gt;
+  &lt;artifactId&gt;project2&lt;/artifactId&gt;
+  &lt;version&gt;${project2Version}&lt;/version&gt;
+  &lt;packaging&gt;jar&lt;/packaging&gt;
+
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;commons-logging&lt;/groupId&gt;
+      &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><p>The project that follows shows how the library can now be used in another project without having to specify the dependent project's versions.</p><div class="source"><pre>&lt;project xmlns=&quot;http://maven.apache.org/POM/4.0.0&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
+     xsi:schemaLocation=&quot;http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&quot;&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;groupId&gt;com.test&lt;/groupId&gt;
+  &lt;artifactId&gt;use&lt;/artifactId&gt;
+  &lt;version&gt;1.0.0&lt;/version&gt;
+  &lt;packaging&gt;jar&lt;/packaging&gt;
+
+  &lt;dependencyManagement&gt;
+    &lt;dependencies&gt;
+      &lt;dependency&gt;
+        &lt;groupId&gt;com.test&lt;/groupId&gt;
+        &lt;artifactId&gt;bom&lt;/artifactId&gt;
+        &lt;version&gt;1.0.0&lt;/version&gt;
+        &lt;type&gt;pom&lt;/type&gt;
+        &lt;scope&gt;import&lt;/scope&gt;
+      &lt;/dependency&gt;
+    &lt;/dependencies&gt;
+  &lt;/dependencyManagement&gt;
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;com.test&lt;/groupId&gt;
+      &lt;artifactId&gt;project1&lt;/artifactId&gt;
+    &lt;/dependency&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;com.test&lt;/groupId&gt;
+      &lt;artifactId&gt;project2&lt;/artifactId&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><p>Finally, when creating projects that import dependencies beware of the following:</p><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"><h3><a name="System_Dependencies">System Dependencies</a></h3><p>Dependencies with the s
 cope <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>
+&lt;project&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;javax.sql&lt;/groupId&gt;
+      &lt;artifactId&gt;jdbc-stdext&lt;/artifactId&gt;
+      &lt;version&gt;2.0&lt;/version&gt;
+      &lt;scope&gt;system&lt;/scope&gt;
+      &lt;systemPath&gt;${java.home}/lib/rt.jar&lt;/systemPath&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+  ...
+&lt;/project&gt;
+</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><div class="source"><pre>&lt;project&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;sun.jdk&lt;/groupId&gt;
+      &lt;artifactId&gt;tools&lt;/artifactId&gt;
+      &lt;version&gt;1.5.0&lt;/version&gt;
+      &lt;scope&gt;system&lt;/scope&gt;
+      &lt;systemPath&gt;${java.home}/../lib/tools.jar&lt;/systemPath&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+  ...
+&lt;/project&gt;</pre></div></div></div>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">
+        &#169;            2002-2012
+              The Apache Software Foundation
+            
+                       - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+        Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+      </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>

Added: websites/staging/maventest/trunk/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html (added)
+++ websites/staging/maventest/trunk/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html Thu Mar  1 16:35:39 2012
@@ -0,0 +1,347 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Optional Dependencies and Dependency Exclusions</title>
+    <style type="text/css" media="all">
+      @import url("../../css/maven-base.css");
+      @import url("../../css/maven-theme.css");
+      @import url("../../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+        <meta name="author" content="Allan Ramirez" />
+        <meta name="Date-Revision-yyyymmdd" content="20120301" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+                                                    
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+                                                        
+<script type="text/javascript">_uacct = "UA-140879-1";
+        urchinTracker();</script>
+                    </head>
+  <body class="composite">
+    <div id="banner">
+                                      <a href="../.././" id="bannerLeft">
+                                                <img src="../../images/apache-maven-project-2.png" alt="" />
+                </a>
+                        <span id="bannerRight">
+                                                <img src="../../images/maven-logo-2.gif" alt="" />
+                </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+            
+                                <div class="xleft">
+                          <a href="http://www.apache.org/" class="externalLink">Apache</a>
+        &gt;
+                  <a href="../../index.html">Maven</a>
+        &gt;
+    Optional Dependencies and Dependency Exclusions
+      </div>
+            <div class="xright">        
+                                 Last Published: 2012-03-01
+            </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+             
+                                                <h5>Main</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../index.html">Welcome</a>
+            </li>
+          </ul>
+                       <h5>Get Maven</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../download.html">Download</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../license.html">License</a>
+            </li>
+          </ul>
+                       <h5>IDE Integration</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../eclipse-plugin.html">Eclipse</a>
+            </li>
+                  <li class="none">
+                  <a href="../../netbeans-module.html">NetBeans</a>
+            </li>
+          </ul>
+                       <h5>About Maven</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../what-is-maven.html">What is Maven?</a>
+            </li>
+                  <li class="none">
+                  <a href="../../maven-features.html">Features</a>
+            </li>
+                  <li class="none">
+                  <a href="../../general.html">FAQ (official)</a>
+            </li>
+                  <li class="none">
+                  <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../powered-by-m2.html">Powered By</a>
+            </li>
+          </ul>
+                       <h5>Documentation</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../plugins/index.html">Maven Plugins</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/index.html">Index (category)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../run-maven/index.html">Running Maven</a>
+            </li>
+                                                                                                                                            <li class="collapsed">
+                  <a href="../../users/index.html">User Centre</a>
+                  </li>
+                                                                                                        <li class="collapsed">
+                  <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+                  </li>
+                  <li class="none">
+                  <a href="../../repository/index.html">Maven Repository Centre</a>
+            </li>
+                  <li class="none">
+                  <a href="../../developers/index.html">Maven Developer Centre</a>
+            </li>
+                  <li class="none">
+                  <a href="../../articles.html">Books and Resources</a>
+            </li>
+                  <li class="none">
+                  <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+            </li>
+          </ul>
+                       <h5>Community</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../community.html">Community Overview</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+            </li>
+                  <li class="none">
+                  <a href="../../users/getting-help.html">Getting Help</a>
+            </li>
+                  <li class="none">
+                  <a href="../../issue-tracking.html">Issue Tracking</a>
+            </li>
+                  <li class="none">
+                  <a href="../../source-repository.html">Source Repository</a>
+            </li>
+                  <li class="none">
+                  <a href="../../team-list.html">The Maven Team</a>
+            </li>
+          </ul>
+                       <h5>Project Documentation</h5>
+                  <ul>
+                                                                                                                          <li class="collapsed">
+                  <a href="../../project-info.html">Project Information</a>
+                  </li>
+          </ul>
+                       <h5>Maven Projects</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../ant-tasks/index.html">Ant Tasks</a>
+            </li>
+                  <li class="none">
+                  <a href="../../archetype/index.html">Archetype</a>
+            </li>
+                  <li class="none">
+                  <a href="../../doxia/index.html">Doxia</a>
+            </li>
+                  <li class="none">
+                  <a href="../../jxr/index.html">JXR</a>
+            </li>
+                  <li class="none">
+                  <a href="../../maven-1.x/index.html">Maven 1.x</a>
+            </li>
+                  <li class="none">
+                  <a href="../../index.html">Maven 2 & 3</a>
+            </li>
+                  <li class="none">
+                  <a href="../../plugins/index.html">Plugins</a>
+            </li>
+                  <li class="none">
+                  <a href="../../scm/index.html">SCM</a>
+            </li>
+                  <li class="none">
+                  <a href="../../shared/index.html">Shared Components</a>
+            </li>
+                  <li class="none">
+                  <a href="../../surefire/index.html">Surefire</a>
+            </li>
+                  <li class="none">
+                  <a href="../../wagon/index.html">Wagon</a>
+            </li>
+          </ul>
+                       <h5>ASF</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+            </li>
+          </ul>
+                                 <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+          <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+        </a>
+                       
+                            </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <!-- Licensed to the Apache Software Foundation (ASF) under one --><!-- or more contributor license agreements.  See the NOTICE file --><!-- distributed with this work for additional information --><!-- regarding copyright ownership.  The ASF licenses this file --><!-- to you under the Apache License, Version 2.0 (the --><!-- "License"); you may not use this file except in compliance --><!-- with the License.  You may obtain a copy of the License at --><!--  --><!-- http://www.apache.org/licenses/LICENSE-2.0 --><!--  --><!-- Unless required by applicable law or agreed to in writing, --><!-- software distributed under the License is distributed on an --><!-- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY --><!-- KIND, either express or implied.  See the License for the --><!-- specific language governing permissions and limitations --><!-- under the License. --><!-- NOTE: For help with the syntax of this file, see: --><!-- http://maven.apache.org/doxia/referen
 ces/apt-format.html --><div class="section"><h2>Introduction<a name="Introduction"></a></h2><p>This section discusses the functionality of optional dependencies and dependency exclusions. This will help users to understand what are they, how to use them, how they work and when is the best way to use them. It also explains why exclusions are made as per dependency basis not in a POM level.</p><div class="section"><h3>Optional Dependencies<a name="Optional_Dependencies"></a></h3><p>Optional dependencies are used when it's not really possible (for whatever reason) to split a project up 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 depended 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 fu
 nctionality. </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 will have to redeclare that optional dependency in their own project. This is not the most clear way to handle this situation, but then again both optional dependencies and dependency exclusions are stop-gap solutions.</p><div class="section"><h4>Why use optional dependencies?<a name="Why_use_optional_dependencies"></a></h4><p>It's not only important to declare optional dependencies in order to save space/memory/etc. It's vital to control the list of actual dependencies a person needs in order to use a project, since these jars may eventually make it into a WAR, EAR, EJB, etc. Inclusion of the wrong jars may violate a license agreement, cause classpath issues, etc. </p></div><div class="section"><h4>How do I use the optional tag?<a name="How_do_I_use_the_optional_
 tag"></a></h4><p>A dependency is declared as optional by simply setting the &lt;optional&gt; tag to true in your dependency declaration. See the sample below:</p><div class="source"><pre>
+&lt;project&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;!-- declare the dependency to be set as optional --&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;sample.ProjectA&lt;/groupId&gt;
+      &lt;artifactId&gt;Project-A&lt;/artifactId&gt;
+      &lt;version&gt;1.0&lt;/version&gt;
+      &lt;scope&gt;compile&lt;/scope&gt;
+      &lt;optional&gt;true&lt;/optional&gt; &lt;!-- value will be true or false only --&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div></div><div class="section"><h4>How do optional dependencies work?<a name="How_do_optional_dependencies_work"></a></h4><div class="source"><pre>
+Project-A -&gt; 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. Its just like a normal build where Project-B will be added in its classpath.</p><div class="source"><pre>
+Project-X -&gt; Project-A
+</pre></div><p>But when another project(Project-X) declares Project-A as a dependency in its POM, the optional dependency takes effect. You'll notice that Project-B is not included in the classpath of Project-X; you will need to declare it directly in your POM in order for B to be included in X's classpath. </p></div><div class="section"><h4>Example<a name="Example"></a></h4><p>Let us say that there is a project named <i>X2</i> that has similar functions with <i>Hibernate</i> which supports many database drivers/dependencies such as mysql, postgre, oracle etc. All of these dependencies are needed for X2 to build but not for your project, so it is very practical for X2 to declare these dependencies as optional, so that whenever your project declares X2 as a direct dependency in your POM, all the drivers supported by the X2 will not be automatically included to your project's classpath instead you'll have to declare it directly on what driver/dependency of the database you are
  going to use.</p></div></div><div class="section"><h3>Dependency Exclusions<a name="Dependency_Exclusions"></a></h3><p>Since maven 2.x resolves dependencies transitively, it is possible for unwanted dependencies to be included in your project's classpath. Projects that you depend on may not have declared their set of dependencies correctly, for example. In order to address this special situtation, maven 2.x has incorporated the notion of explicit dependency exclusion. 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"><h4>How to use dependency exclusions<a name="How_to_use_dependency_exclusions"></a></h4><p>We add the &lt;exclusions&gt; tag under the &lt;dependency&gt; section of the pom.</p><div class="source"><pre>
+&lt;project&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;sample.ProjectA&lt;/groupId&gt;
+      &lt;artifactId&gt;Project-A&lt;/artifactId&gt;
+      &lt;version&gt;1.0&lt;/version&gt;
+      &lt;scope&gt;compile&lt;/scope&gt;
+      &lt;exclusions&gt;
+        &lt;exclusion&gt;  &lt;!-- declare the exclusion here --&gt;
+          &lt;groupId&gt;sample.ProjectB&lt;/groupId&gt;
+          &lt;artifactId&gt;Project-B&lt;/artifactId&gt;
+        &lt;/exclusion&gt;
+      &lt;/exclusions&gt; 
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div></div><div class="section"><h4>How dependency exclusion works and when to use it <b>( as a last resort! )</b><a name="How_dependency_exclusion_works_and_when_to_use_it__as_a_last_resort_"></a></h4><div class="source"><pre>
+Project-A
+   -&gt; Project-B
+        -&gt; Project-D &lt;! -- This dependency should be excluded --&gt;
+              -&gt; Project-E
+              -&gt; Project-F
+   -&gt; 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>B, C, D, E, F</pre></div><p>What if we dont want project D and its dependencies to be added to Project A's classpath because we know some of Project-D's dependencies (maybe Project-E for example) was missing from the repository, and you don't need/want the functionality in Project-B that depends on Project-D anyway. In this case, Project-B's developers could provide a dependency on Project-D that is &lt;optional&gt;true&lt;/optional&gt;, like this:</p><div class="source"><pre>&lt;dependency&gt;
+  &lt;groupId&gt;sample.ProjectD&lt;/groupId&gt;
+  &lt;artifactId&gt;ProjectD&lt;/artifactId&gt;
+  &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;
+  &lt;optional&gt;true&lt;/optional&gt;
+&lt;/dependency&gt;</pre></div><p>HOWEVER, they didn't. As a last resort, you still have the option to exclude it on your side, in Project-A, like this:</p><div class="source"><pre>
+&lt;project&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;groupId&gt;sample.ProjectA&lt;/groupId&gt;
+  &lt;artifactId&gt;Project-A&lt;/artifactId&gt;
+  &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;
+  &lt;packaging&gt;jar&lt;/packaging&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;sample.ProjectB&lt;/groupId&gt;
+      &lt;artifactId&gt;Project-B&lt;/artifactId&gt;
+      &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;
+      &lt;exclusions&gt;
+        &lt;exclusion&gt;
+          &lt;groupId&gt;sample.ProjectD&lt;/groupId&gt; &lt;!-- Exclude Project-D from Project-B --&gt;
+          &lt;artifactId&gt;Project-D&lt;/artifactId&gt;
+        &lt;/exclusion&gt;
+      &lt;/exclusions&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div><p>If we deploy the Project-A to a repository, and Project-X declares a normal dependency on Project-A, will Project-D be excluded from the classpath still?</p><div class="source"><pre>
+Project-X -&gt; 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>
+Project-X -&gt; Project-Y
+               -&gt; Project-B
+                    -&gt; Project-D
+                       ...
+</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 we 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, what if the dependency we don't want is Project-E instead of Project-D. How will we exclude it? See the diagram below:</p><div class="source"><pre>
+Project-A
+   -&gt; Project-B
+        -&gt; Project-D 
+              -&gt; Project-E &lt;!-- Exclude this dependency --&gt;
+              -&gt; Project-F
+   -&gt; Project C
+</pre></div><p>Exclusions work on the entire dependency graph below the point where they are declared. If you wanted to exclude Project-E instead of Project-D, you'd simply change the exclusion to point at Project-E, but you wouldn't move the exclusion down to Project-D...you cannot change Project-D's POM. If you could, you would use optional dependencies instead of exclusions, or split Project-D up into multiple subprojects, each with nothing but normal dependencies. </p><div class="source"><pre>
+&lt;project&gt;
+  &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+  &lt;groupId&gt;sample.ProjectA&lt;/groupId&gt;
+  &lt;artifactId&gt;Project-A&lt;/artifactId&gt;
+  &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;
+  &lt;packaging&gt;jar&lt;/packaging&gt;
+  ...
+  &lt;dependencies&gt;
+    &lt;dependency&gt;
+      &lt;groupId&gt;sample.ProjectB&lt;/groupId&gt;
+      &lt;artifactId&gt;Project-B&lt;/artifactId&gt;
+      &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;
+      &lt;exclusions&gt;
+        &lt;exclusion&gt;
+          &lt;groupId&gt;sample.ProjectE&lt;/groupId&gt; &lt;!-- Exclude Project-E from Project-B --&gt;
+          &lt;artifactId&gt;Project-E&lt;/artifactId&gt;
+        &lt;/exclusion&gt;
+      &lt;/exclusions&gt;
+    &lt;/dependency&gt;
+  &lt;/dependencies&gt;
+&lt;/project&gt;
+</pre></div></div><div class="section"><h4>Why exclusions are made on a per-dependency basis, rather than at the POM level<a name="Why_exclusions_are_made_on_a_per-dependency_basis_rather_than_at_the_POM_level"></a></h4><p>This is mainly done 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></div></div></div>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">
+        &#169;            2002-2012
+              The Apache Software Foundation
+            
+                       - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+        Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+      </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>

Added: websites/staging/maventest/trunk/content/guides/introduction/introduction-to-plugin-prefix-mapping.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/introduction/introduction-to-plugin-prefix-mapping.html (added)
+++ websites/staging/maventest/trunk/content/guides/introduction/introduction-to-plugin-prefix-mapping.html Thu Mar  1 16:35:39 2012
@@ -0,0 +1,260 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Introduction to Plugin Prefix Resolution</title>
+    <style type="text/css" media="all">
+      @import url("../../css/maven-base.css");
+      @import url("../../css/maven-theme.css");
+      @import url("../../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+        <meta name="author" content="John Casey" />
+        <meta name="Date-Creation-yyyymmdd" content="20090801" />
+    <meta name="Date-Revision-yyyymmdd" content="20120301" />
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+                                                    
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+                                                        
+<script type="text/javascript">_uacct = "UA-140879-1";
+        urchinTracker();</script>
+                    </head>
+  <body class="composite">
+    <div id="banner">
+                                      <a href="../.././" id="bannerLeft">
+                                                <img src="../../images/apache-maven-project-2.png" alt="" />
+                </a>
+                        <span id="bannerRight">
+                                                <img src="../../images/maven-logo-2.gif" alt="" />
+                </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+            
+                                <div class="xleft">
+                          <a href="http://www.apache.org/" class="externalLink">Apache</a>
+        &gt;
+                  <a href="../../index.html">Maven</a>
+        &gt;
+    Introduction to Plugin Prefix Resolution
+      </div>
+            <div class="xright">        
+                                 Last Published: 2012-03-01
+            </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+             
+                                                <h5>Main</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../index.html">Welcome</a>
+            </li>
+          </ul>
+                       <h5>Get Maven</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../download.html">Download</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../license.html">License</a>
+            </li>
+          </ul>
+                       <h5>IDE Integration</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../eclipse-plugin.html">Eclipse</a>
+            </li>
+                  <li class="none">
+                  <a href="../../netbeans-module.html">NetBeans</a>
+            </li>
+          </ul>
+                       <h5>About Maven</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../what-is-maven.html">What is Maven?</a>
+            </li>
+                  <li class="none">
+                  <a href="../../maven-features.html">Features</a>
+            </li>
+                  <li class="none">
+                  <a href="../../general.html">FAQ (official)</a>
+            </li>
+                  <li class="none">
+                  <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../powered-by-m2.html">Powered By</a>
+            </li>
+          </ul>
+                       <h5>Documentation</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../plugins/index.html">Maven Plugins</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/index.html">Index (category)</a>
+            </li>
+                  <li class="none">
+                  <a href="../../run-maven/index.html">Running Maven</a>
+            </li>
+                                                                                                                                            <li class="collapsed">
+                  <a href="../../users/index.html">User Centre</a>
+                  </li>
+                                                                                                        <li class="collapsed">
+                  <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+                  </li>
+                  <li class="none">
+                  <a href="../../repository/index.html">Maven Repository Centre</a>
+            </li>
+                  <li class="none">
+                  <a href="../../developers/index.html">Maven Developer Centre</a>
+            </li>
+                  <li class="none">
+                  <a href="../../articles.html">Books and Resources</a>
+            </li>
+                  <li class="none">
+                  <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+            </li>
+          </ul>
+                       <h5>Community</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../community.html">Community Overview</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+            </li>
+                  <li class="none">
+                  <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+            </li>
+                  <li class="none">
+                  <a href="../../users/getting-help.html">Getting Help</a>
+            </li>
+                  <li class="none">
+                  <a href="../../issue-tracking.html">Issue Tracking</a>
+            </li>
+                  <li class="none">
+                  <a href="../../source-repository.html">Source Repository</a>
+            </li>
+                  <li class="none">
+                  <a href="../../team-list.html">The Maven Team</a>
+            </li>
+          </ul>
+                       <h5>Project Documentation</h5>
+                  <ul>
+                                                                                                                          <li class="collapsed">
+                  <a href="../../project-info.html">Project Information</a>
+                  </li>
+          </ul>
+                       <h5>Maven Projects</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="../../ant-tasks/index.html">Ant Tasks</a>
+            </li>
+                  <li class="none">
+                  <a href="../../archetype/index.html">Archetype</a>
+            </li>
+                  <li class="none">
+                  <a href="../../doxia/index.html">Doxia</a>
+            </li>
+                  <li class="none">
+                  <a href="../../jxr/index.html">JXR</a>
+            </li>
+                  <li class="none">
+                  <a href="../../maven-1.x/index.html">Maven 1.x</a>
+            </li>
+                  <li class="none">
+                  <a href="../../index.html">Maven 2 & 3</a>
+            </li>
+                  <li class="none">
+                  <a href="../../plugins/index.html">Plugins</a>
+            </li>
+                  <li class="none">
+                  <a href="../../scm/index.html">SCM</a>
+            </li>
+                  <li class="none">
+                  <a href="../../shared/index.html">Shared Components</a>
+            </li>
+                  <li class="none">
+                  <a href="../../surefire/index.html">Surefire</a>
+            </li>
+                  <li class="none">
+                  <a href="../../wagon/index.html">Wagon</a>
+            </li>
+          </ul>
+                       <h5>ASF</h5>
+                  <ul>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+            </li>
+                  <li class="none">
+                  <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+            </li>
+          </ul>
+                                 <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+          <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+        </a>
+                       
+                            </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <!-- Licensed to the Apache Software Foundation (ASF) under one --><!-- or more contributor license agreements.  See the NOTICE file --><!-- distributed with this work for additional information --><!-- regarding copyright ownership.  The ASF licenses this file --><!-- to you under the Apache License, Version 2.0 (the --><!-- "License"); you may not use this file except in compliance --><!-- with the License.  You may obtain a copy of the License at --><!--  --><!-- http://www.apache.org/licenses/LICENSE-2.0 --><!--  --><!-- Unless required by applicable law or agreed to in writing, --><!-- software distributed under the License is distributed on an --><!-- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY --><!-- KIND, either express or implied.  See the License for the --><!-- specific language governing permissions and limitations --><!-- under the License. --><!-- NOTE: For help with the syntax of this file, see: --><!-- http://maven.apache.org/doxia/referen
 ces/apt-format.html --><div class="section"><h2>Introduction to Plugin Prefix Resolution<a name="Introduction_to_Plugin_Prefix_Resolution"></a></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 provid
 es 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"><h3>Specifying a Plugin's Prefix<a name="Specifying_a_Plugins_Prefix"></a></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 &quot;maven&quot; or &quot;plugin&quot; surrounded by dashes in the plugin's artifact ID. The conventional artifact ID formats to use are:</p><ul><li><tt>maven-${prefix}-plugin</tt> - for plugins from the Apache Maven project</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 metad
 ata 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><div class="source"><pre>&lt;project&gt;
+  ...
+  &lt;build&gt;
+    ...
+    &lt;plugins&gt;
+      ...
+      &lt;plugin&gt;
+        &lt;artifactId&gt;maven-plugin-plugin&lt;/artifactId&gt;
+        &lt;version&gt;2.3&lt;/version&gt;
+        &lt;configuration&gt;
+          ...
+          &lt;goalPrefix&gt;somePrefix&lt;/goalPrefix&gt;
+        &lt;/configuration&gt;
+      &lt;/plugin&gt;
+    &lt;/plugins&gt;
+  &lt;/build&gt;
+&lt;/project&gt;</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>mvn somePrefix:goal</pre></div></div><div class="section"><h3>Mapping Prefixes to Plugins<a name="Mapping_Prefixes_to_Plugins"></a></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>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>g
 roupId</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"><h3>Configuring Maven to Search for Plugins<a name="Configuring_Maven_to_Search_for_Plugins"></a></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 con
 trol 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>~/.m2/settings.xml</tt>; global: <tt>$M2_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><div class="source"><pre>&lt;pluginGroups&gt;
+  &lt;pluginGroup&gt;org.codehaus.modello&lt;/pluginGroup&gt;
+&lt;/pluginGroups&gt;</pre></div><p>This allows me to execute the following, which will generate Java classes from the model:</p><div class="source"><pre>mvn -Dversion=4.0.0 -Dmodel=maven.mdo modello:java</pre></div><p>Maven will always search the following groupId's <b>after</b> searching any plugin groups specified in the user's settings:</p><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"><h3>Resources<a name="Resources"></a></h3><p><a name="a1">1</a> <a href="../mini/guide-configuring-maven.html">Guide to Configuring Maven</a></p></div><
 /div>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">
+        &#169;            2002-2012
+              The Apache Software Foundation
+            
+                       - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+        Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+      </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>



Mime
View raw message