View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.eclipse.aether.util.graph.manager;
20  
21  import java.util.ArrayList;
22  import java.util.Collection;
23  
24  import org.eclipse.aether.collection.DependencyCollectionContext;
25  import org.eclipse.aether.collection.DependencyManager;
26  import org.eclipse.aether.graph.Exclusion;
27  import org.eclipse.aether.scope.ScopeManager;
28  import org.eclipse.aether.scope.SystemDependencyScope;
29  
30  /**
31   * A dependency manager that mimics the way Maven 2.x works for backward compatibility.
32   *
33   * <h2>Overview</h2>
34   * <p>
35   * This manager was used throughout all Maven 3.x versions for backward compatibility reasons.
36   * It provides the exact same dependency management behavior as Maven 2.x, which differs
37   * significantly from modern dependency management approaches.
38   * </p>
39   *
40   * <h2>Key Characteristics</h2>
41   * <ul>
42   * <li><strong>Exclusion Handling:</strong> Ignores exclusions introduced by direct dependencies</li>
43   * <li><strong>Management Scope:</strong> Only obeys root management, ignoring intermediate management</li>
44   * <li><strong>Depth Behavior:</strong> {@code deriveUntil=2}, {@code applyFrom=2} with special "hop" at {@code depth=1}</li>
45   * <li><strong>Level 1 Skip:</strong> Ignores context from depth=1 for Maven 2.x compatibility</li>
46   * </ul>
47   *
48   * <h2>When to Use</h2>
49   * <p>
50   * Use this manager when you need exact Maven 2.x compatibility behavior or when working
51   * with legacy projects that depend on Maven 2.x dependency resolution semantics.
52   * </p>
53   *
54   * <h2>Comparison with Other Managers</h2>
55   * <p>
56   * Unlike {@link TransitiveDependencyManager} and {@link DefaultDependencyManager}, this manager
57   * deliberately ignores certain dependency management rules to maintain backward compatibility.
58   * See {@code MavenITmng4720DependencyManagementExclusionMergeTest} for behavioral differences.
59   * </p>
60   *
61   * @see TransitiveDependencyManager
62   * @see DefaultDependencyManager
63   */
64  public final class ClassicDependencyManager extends AbstractDependencyManager {
65      /**
66       * Creates a new dependency manager without any management information.
67       *
68       * @deprecated Use {@link #ClassicDependencyManager(ScopeManager)} instead to provide
69       *             application-specific scope management. This constructor uses legacy system
70       *             dependency scope handling which may not be appropriate for all use cases.
71       */
72      @Deprecated
73      public ClassicDependencyManager() {
74          this(null);
75      }
76  
77      /**
78       * Creates a new dependency manager without any management information.
79       * <p>
80       * This constructor initializes the manager with Maven 2.x compatible behavior:
81       * <ul>
82       * <li>deriveUntil = 2 (collect rules only from root level)</li>
83       * <li>applyFrom = 2 (apply rules starting from depth 2)</li>
84       * <li>Special depth=1 handling for backward compatibility</li>
85       * </ul>
86       *
87       * @param scopeManager application-specific scope manager for handling system dependencies,
88       *                     may be null to use legacy system dependency scope handling
89       * @since 2.0.12
90       */
91      public ClassicDependencyManager(ScopeManager scopeManager) {
92          super(2, 2, scopeManager);
93      }
94  
95      @SuppressWarnings("checkstyle:ParameterNumber")
96      private ClassicDependencyManager(
97              ArrayList<AbstractDependencyManager> path,
98              int depth,
99              int deriveUntil,
100             int applyFrom,
101             MMap<Key, String> managedVersions,
102             MMap<Key, String> managedScopes,
103             MMap<Key, Boolean> managedOptionals,
104             MMap<Key, String> managedLocalPaths,
105             MMap<Key, Holder<Collection<Exclusion>>> managedExclusions,
106             SystemDependencyScope systemDependencyScope) {
107         super(
108                 path,
109                 depth,
110                 deriveUntil,
111                 applyFrom,
112                 managedVersions,
113                 managedScopes,
114                 managedOptionals,
115                 managedLocalPaths,
116                 managedExclusions,
117                 systemDependencyScope);
118     }
119 
120     /**
121      * Derives a child manager with Maven 2.x compatibility behavior.
122      * <p>
123      * <strong>Critical Maven 2.x Compatibility:</strong> This method implements a special
124      * "hop" at depth=1 that skips dependency management collection at that level. This
125      * behavior is essential for Maven 2.x compatibility and is verified by integration tests.
126      * </p>
127      * <p>
128      * <strong>Why the depth=1 skip is necessary:</strong> Maven 2.x did not collect dependency
129      * management from first-level dependencies, only from the root. Removing this skip would
130      * break backward compatibility with Maven 2.x projects.
131      * </p>
132      *
133      * @param context the dependency collection context
134      * @return a new child manager or the current instance with passed-through management
135      * @see <a href="https://github.com/apache/maven-integration-testing/blob/master/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng4720DependencyManagementExclusionMergeTest.java">MNG-4720 Integration Test</a>
136      */
137     @Override
138     public DependencyManager deriveChildManager(DependencyCollectionContext context) {
139         // MNG-4720: Maven2 backward compatibility
140         // Removing this IF makes one IT fail here (read comment above):
141         // https://github.com/apache/maven-integration-testing/blob/b4e8fd52b99a058336f9c7c5ec44fdbc1427759c/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng4720DependencyManagementExclusionMergeTest.java#L67
142         // Skipping level=1 (maven2 compatibility); see MavenITmng4720DependencyManagementExclusionMergeTest
143         if (depth == 1) {
144             return newInstance(managedVersions, managedScopes, managedOptionals, managedLocalPaths, managedExclusions);
145         }
146         return super.deriveChildManager(context);
147     }
148 
149     @Override
150     protected DependencyManager newInstance(
151             MMap<Key, String> managedVersions,
152             MMap<Key, String> managedScopes,
153             MMap<Key, Boolean> managedOptionals,
154             MMap<Key, String> managedLocalPaths,
155             MMap<Key, Holder<Collection<Exclusion>>> managedExclusions) {
156         ArrayList<AbstractDependencyManager> path = new ArrayList<>(this.path);
157         path.add(this);
158         return new ClassicDependencyManager(
159                 path,
160                 depth + 1,
161                 deriveUntil,
162                 applyFrom,
163                 managedVersions,
164                 managedScopes,
165                 managedOptionals,
166                 managedLocalPaths,
167                 managedExclusions,
168                 systemDependencyScope);
169     }
170 }