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.impl.scope;
020
021import java.util.Collection;
022import java.util.Collections;
023import java.util.Optional;
024import java.util.Set;
025
026import org.eclipse.aether.RepositorySystemSession;
027import org.eclipse.aether.collection.CollectResult;
028import org.eclipse.aether.scope.DependencyScope;
029import org.eclipse.aether.scope.ResolutionScope;
030import org.eclipse.aether.scope.ScopeManager;
031import org.eclipse.aether.scope.SystemDependencyScope;
032
033/**
034 * Internal scope manager.
035 *
036 * @since 2.0.0
037 */
038public interface InternalScopeManager extends ScopeManager {
039    /**
040     * The "width" of scope: is basically sum of all distinct {@link ProjectPath} and {@link BuildPath} that are
041     * in build scopes the scope is present in. The more of them, the "wider" is the scope. Transitive scopes are
042     * weighted more as well.
043     * <p>
044     * The {@link ProjectPath#order()} makes given path "weigh" more. So a scope being present only in
045     * "main" project path is wider than scope being present only in "test" project path.
046     * <p>
047     * Interpretation: the bigger the returned integer is, the "wider" the scope is. The numbers should not serve
048     * any other purposes, merely to sort scope instances by "width" (i.e. from "widest" to "narrowest").
049     */
050    int getDependencyScopeWidth(DependencyScope dependencyScope);
051
052    /**
053     * Returns the {@link BuildScope} that this scope deem as main.
054     */
055    Optional<BuildScope> getDependencyScopeMainProjectBuildScope(DependencyScope dependencyScope);
056
057    /**
058     * Resolver specific: post-processing to be used to support this scope (with its dependency
059     * and resolution scopes).
060     */
061    CollectResult postProcess(
062            RepositorySystemSession session, ResolutionScope resolutionScope, CollectResult collectResult);
063
064    /**
065     * The mode of resolution scope: eliminate (remove all occurrences) or just remove.
066     */
067    enum Mode {
068        /**
069         * Mode where artifacts in non-wanted scopes are completely eliminated. In other words, this mode ensures
070         * that if a dependency was removed due unwanted scope, it is guaranteed that no such dependency will appear
071         * anywhere else in the resulting graph either.
072         */
073        ELIMINATE,
074
075        /**
076         * Mode where artifacts in non-wanted scopes are removed only. In other words, they will NOT prevent (as in
077         * they will not "dominate") other possibly appearing occurrences of same artifact in the graph.
078         */
079        REMOVE
080    }
081
082    /**
083     * Creates dependency scope instance.
084     * <p>
085     * Should be invoked only via {@link ScopeManagerConfiguration#buildDependencyScopes(InternalScopeManager)}.
086     */
087    DependencyScope createDependencyScope(String id, boolean transitive, Collection<BuildScopeQuery> presence);
088
089    /**
090     * Creates system dependency scope instance. This method may be invoked only once, as there can be only one
091     * instance of {@link SystemDependencyScope}!
092     * <p>
093     * Should be invoked only via {@link ScopeManagerConfiguration#buildDependencyScopes(InternalScopeManager)}.
094     */
095    SystemDependencyScope createSystemDependencyScope(
096            String id, boolean transitive, Collection<BuildScopeQuery> presence, String systemPathProperty);
097
098    /**
099     * Creates resolution scope instance.
100     * <p>
101     * Should be invoked only via {@link ScopeManagerConfiguration#buildResolutionScopes(InternalScopeManager)}.
102     */
103    default ResolutionScope createResolutionScope(
104            String id,
105            Mode mode,
106            Collection<BuildScopeQuery> wantedPresence,
107            Collection<DependencyScope> explicitlyIncluded,
108            Collection<DependencyScope> transitivelyExcluded) {
109        return createResolutionScope(
110                id, Collections.emptySet(), mode, wantedPresence, explicitlyIncluded, transitivelyExcluded);
111    }
112
113    /**
114     * Creates resolution scope instance with aliases.
115     * <p>
116     * Should be invoked only via {@link ScopeManagerConfiguration#buildResolutionScopes(InternalScopeManager)}.
117     *
118     * @since 2.0.18
119     */
120    ResolutionScope createResolutionScope(
121            String id,
122            Set<String> aliases,
123            Mode mode,
124            Collection<BuildScopeQuery> wantedPresence,
125            Collection<DependencyScope> explicitlyIncluded,
126            Collection<DependencyScope> transitivelyExcluded);
127}