Index: src/site/apt/guides/introduction/introduction-to-dependency-mechanism.apt =================================================================== --- src/site/apt/guides/introduction/introduction-to-dependency-mechanism.apt (revision 519246) +++ src/site/apt/guides/introduction/introduction-to-dependency-mechanism.apt (working copy) @@ -51,6 +51,13 @@ 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 + * + - this allows project authors to directly specify the versions of artifiacts 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. + * - this allows you to only include dependencies appropriate for the current stage of the build. This is described in more detail below. @@ -271,9 +278,111 @@ identity set to <<\{groupId, artifactId\}>>, since the default for the type field is <<>>, and the default classifier is null. + 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: + Project A: + ++----+ + + + 4.0.0 + maven + A + pom + A + 1.0 + + + + test + a + 1.2 + + + test + b + 1.0 + compile + + + test + c + 1.0 + compile + + + test + d + 1.2 + + + + + ++----+ + + Project B: + ++----+ + + + + A + maven + 1.0 + + 4.0.0 + maven + B + pom + B + 1.0 + + + + test + d + 1.0 + + + + + + maven-test + a + 1.0 + runtime + + + maven-test + c + runtime + + + + ++----+ + + 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. + + * 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. + + * b is defined in B's parent's dependency managemnet 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. + + * 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. + + [] + The reference information about the dependency management tags is available from the - {{{maven-model/maven.html#class_DependencyManagement}project descriptor reference}}. ----- + {{{../../ref/current/maven-model/maven.html#class_DependencyManagement}project descriptor reference}}. * System Dependencies Index: src/site/apt/pom.apt =================================================================== --- src/site/apt/pom.apt (revision 519246) +++ src/site/apt/pom.apt (working copy) @@ -565,16 +565,18 @@ *** {Dependency Management} Besides inheriting certain top-level elements, parents have elements to configure values for - child POMs that do not affect the parent’s own build lifecycle. One of those elements is + child POMs and transitive dependencies. One of those elements is <<>>. * <>: - is used only by parent POMs to help manage dependency information across all of its children. + is used by POMs to help manage dependency information across all of its children. If the <<>> project uses <<>> to define a dependency on <<>>, then POMs inheriting from this one can set their dependency giving the <<>>=<<>> and <<>>=<<>> only, then Maven will fill in the <<>> set by the parent. The benefits of this method are obvious. Dependency - details can be set in one central location, which will propagate to all inheriting POMs. + details can be set in one central location, which will propagate to all inheriting POMs. In + addition, the version and scope of artifacts which are incorporated from transitive dependencies + may also be controlled by specifying them in a dependency management section. ** {Aggregation} (or Multi-Module)