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.resolution;
020
021import org.eclipse.aether.RepositorySystem;
022import org.eclipse.aether.RequestTrace;
023import org.eclipse.aether.artifact.Artifact;
024import org.eclipse.aether.collection.CollectRequest;
025import org.eclipse.aether.graph.DependencyFilter;
026import org.eclipse.aether.graph.DependencyNode;
027
028/**
029 * A request to resolve transitive dependencies. This request can either be supplied with a {@link CollectRequest} to
030 * calculate the transitive dependencies or with an already resolved dependency graph.
031 *
032 * @see RepositorySystem#resolveDependencies(org.eclipse.aether.RepositorySystemSession, DependencyRequest)
033 * @see Artifact#getFile()
034 */
035public final class DependencyRequest {
036
037    private DependencyNode root;
038
039    private CollectRequest collectRequest;
040
041    private DependencyFilter filter;
042
043    private RequestTrace trace;
044
045    /**
046     * Creates an uninitialized request. Note that either {@link #setRoot(DependencyNode)} or
047     * {@link #setCollectRequest(CollectRequest)} must eventually be called to create a valid request.
048     */
049    public DependencyRequest() {
050        // enables default constructor
051    }
052
053    /**
054     * Creates a request for the specified dependency graph and with the given resolution filter.
055     *
056     * @param node The root node of the dependency graph whose artifacts should be resolved, may be {@code null}.
057     * @param filter The resolution filter to use, may be {@code null}.
058     */
059    public DependencyRequest(DependencyNode node, DependencyFilter filter) {
060        setRoot(node);
061        setFilter(filter);
062    }
063
064    /**
065     * Creates a request for the specified collect request and with the given resolution filter.
066     *
067     * @param request The collect request used to calculate the dependency graph whose artifacts should be resolved, may
068     *            be {@code null}.
069     * @param filter The resolution filter to use, may be {@code null}.
070     */
071    public DependencyRequest(CollectRequest request, DependencyFilter filter) {
072        setCollectRequest(request);
073        setFilter(filter);
074    }
075
076    /**
077     * Gets the root node of the dependency graph whose artifacts should be resolved.
078     *
079     * @return The root node of the dependency graph or {@code null} if none.
080     */
081    public DependencyNode getRoot() {
082        return root;
083    }
084
085    /**
086     * Sets the root node of the dependency graph whose artifacts should be resolved. When this request is processed,
087     * the nodes of the given dependency graph will be updated to refer to the resolved artifacts. Eventually, either
088     * {@link #setRoot(DependencyNode)} or {@link #setCollectRequest(CollectRequest)} must be called to create a valid
089     * request.
090     *
091     * @param root The root node of the dependency graph, may be {@code null}.
092     * @return This request for chaining, never {@code null}.
093     */
094    public DependencyRequest setRoot(DependencyNode root) {
095        this.root = root;
096        return this;
097    }
098
099    /**
100     * Gets the collect request used to calculate the dependency graph whose artifacts should be resolved.
101     *
102     * @return The collect request or {@code null} if none.
103     */
104    public CollectRequest getCollectRequest() {
105        return collectRequest;
106    }
107
108    /**
109     * Sets the collect request used to calculate the dependency graph whose artifacts should be resolved. Eventually,
110     * either {@link #setRoot(DependencyNode)} or {@link #setCollectRequest(CollectRequest)} must be called to create a
111     * valid request. If this request is supplied with a dependency node via {@link #setRoot(DependencyNode)}, the
112     * collect request is ignored.
113     *
114     * @param collectRequest The collect request, may be {@code null}.
115     * @return This request for chaining, never {@code null}.
116     */
117    public DependencyRequest setCollectRequest(CollectRequest collectRequest) {
118        this.collectRequest = collectRequest;
119        return this;
120    }
121
122    /**
123     * Gets the resolution filter used to select which artifacts of the dependency graph should be resolved.
124     *
125     * @return The resolution filter or {@code null} to resolve all artifacts of the dependency graph.
126     */
127    public DependencyFilter getFilter() {
128        return filter;
129    }
130
131    /**
132     * Sets the resolution filter used to select which artifacts of the dependency graph should be resolved. For
133     * example, use this filter to restrict resolution to dependencies of a certain scope.
134     *
135     * @param filter The resolution filter, may be {@code null} to resolve all artifacts of the dependency graph.
136     * @return This request for chaining, never {@code null}.
137     */
138    public DependencyRequest setFilter(DependencyFilter filter) {
139        this.filter = filter;
140        return this;
141    }
142
143    /**
144     * Gets the trace information that describes the higher level request/operation in which this request is issued.
145     *
146     * @return The trace information about the higher level operation or {@code null} if none.
147     */
148    public RequestTrace getTrace() {
149        return trace;
150    }
151
152    /**
153     * Sets the trace information that describes the higher level request/operation in which this request is issued.
154     *
155     * @param trace The trace information about the higher level operation, may be {@code null}.
156     * @return This request for chaining, never {@code null}.
157     */
158    public DependencyRequest setTrace(RequestTrace trace) {
159        this.trace = trace;
160        return this;
161    }
162
163    @Override
164    public String toString() {
165        if (root != null) {
166            return String.valueOf(root);
167        }
168        return String.valueOf(collectRequest);
169    }
170}