001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.util.graph.manager;
020
021import java.util.ArrayList;
022import java.util.Collection;
023
024import org.eclipse.aether.collection.DependencyCollectionContext;
025import org.eclipse.aether.collection.DependencyManager;
026import org.eclipse.aether.graph.Exclusion;
027import org.eclipse.aether.scope.ScopeManager;
028import org.eclipse.aether.scope.SystemDependencyScope;
029
030/**
031 * A dependency manager that mimics the way Maven 2.x works for backward compatibility.
032 *
033 * <h2>Overview</h2>
034 * <p>
035 * This manager was used throughout all Maven 3.x versions for backward compatibility reasons.
036 * It provides the exact same dependency management behavior as Maven 2.x, which differs
037 * significantly from modern dependency management approaches.
038 * </p>
039 *
040 * <h2>Key Characteristics</h2>
041 * <ul>
042 * <li><strong>Exclusion Handling:</strong> Ignores exclusions introduced by direct dependencies</li>
043 * <li><strong>Management Scope:</strong> Only obeys root management, ignoring intermediate management</li>
044 * <li><strong>Depth Behavior:</strong> {@code deriveUntil=2}, {@code applyFrom=2} with special "hop" at {@code depth=1}</li>
045 * <li><strong>Level 1 Skip:</strong> Ignores context from depth=1 for Maven 2.x compatibility</li>
046 * </ul>
047 *
048 * <h2>When to Use</h2>
049 * <p>
050 * Use this manager when you need exact Maven 2.x compatibility behavior or when working
051 * with legacy projects that depend on Maven 2.x dependency resolution semantics.
052 * </p>
053 *
054 * <h2>Comparison with Other Managers</h2>
055 * <p>
056 * Unlike {@link TransitiveDependencyManager} and {@link DefaultDependencyManager}, this manager
057 * deliberately ignores certain dependency management rules to maintain backward compatibility.
058 * See {@code MavenITmng4720DependencyManagementExclusionMergeTest} for behavioral differences.
059 * </p>
060 *
061 * @see TransitiveDependencyManager
062 * @see DefaultDependencyManager
063 */
064public final class ClassicDependencyManager extends AbstractDependencyManager {
065    /**
066     * Creates a new dependency manager without any management information.
067     *
068     * @deprecated Use {@link #ClassicDependencyManager(ScopeManager)} instead to provide
069     *             application-specific scope management. This constructor uses legacy system
070     *             dependency scope handling which may not be appropriate for all use cases.
071     */
072    @Deprecated
073    public ClassicDependencyManager() {
074        this(null);
075    }
076
077    /**
078     * Creates a new dependency manager without any management information.
079     * <p>
080     * This constructor initializes the manager with Maven 2.x compatible behavior:
081     * <ul>
082     * <li>deriveUntil = 2 (collect rules only from root level)</li>
083     * <li>applyFrom = 2 (apply rules starting from depth 2)</li>
084     * <li>Special depth=1 handling for backward compatibility</li>
085     * </ul>
086     *
087     * @param scopeManager application-specific scope manager for handling system dependencies,
088     *                     may be null to use legacy system dependency scope handling
089     * @since 2.0.12
090     */
091    public ClassicDependencyManager(ScopeManager scopeManager) {
092        super(2, 2, scopeManager);
093    }
094
095    @SuppressWarnings("checkstyle:ParameterNumber")
096    private ClassicDependencyManager(
097            ArrayList<AbstractDependencyManager> path,
098            int depth,
099            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}