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