001package org.eclipse.aether.resolution;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 * 
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 * 
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import org.eclipse.aether.RepositorySystem;
023import org.eclipse.aether.RepositorySystemSession;
024import org.eclipse.aether.RequestTrace;
025import org.eclipse.aether.artifact.Artifact;
026import org.eclipse.aether.collection.CollectRequest;
027import org.eclipse.aether.graph.DependencyFilter;
028import org.eclipse.aether.graph.DependencyNode;
029
030/**
031 * A request to resolve transitive dependencies. This request can either be supplied with a {@link CollectRequest} to
032 * calculate the transitive dependencies or with an already resolved dependency graph.
033 * 
034 * @see RepositorySystem#resolveDependencies(RepositorySystemSession, DependencyRequest)
035 * @see Artifact#getFile()
036 */
037public final class DependencyRequest
038{
039
040    private DependencyNode root;
041
042    private CollectRequest collectRequest;
043
044    private DependencyFilter filter;
045
046    private RequestTrace trace;
047
048    /**
049     * Creates an uninitialized request. Note that either {@link #setRoot(DependencyNode)} or
050     * {@link #setCollectRequest(CollectRequest)} must eventually be called to create a valid request.
051     */
052    public DependencyRequest()
053    {
054        // enables default constructor
055    }
056
057    /**
058     * Creates a request for the specified dependency graph and with the given resolution filter.
059     * 
060     * @param node The root node of the dependency graph whose artifacts should be resolved, may be {@code null}.
061     * @param filter The resolution filter to use, may be {@code null}.
062     */
063    public DependencyRequest( DependencyNode node, DependencyFilter filter )
064    {
065        setRoot( node );
066        setFilter( filter );
067    }
068
069    /**
070     * Creates a request for the specified collect request and with the given resolution filter.
071     * 
072     * @param request The collect request used to calculate the dependency graph whose artifacts should be resolved, may
073     *            be {@code null}.
074     * @param filter The resolution filter to use, may be {@code null}.
075     */
076    public DependencyRequest( CollectRequest request, DependencyFilter filter )
077    {
078        setCollectRequest( request );
079        setFilter( filter );
080    }
081
082    /**
083     * Gets the root node of the dependency graph whose artifacts should be resolved.
084     * 
085     * @return The root node of the dependency graph or {@code null} if none.
086     */
087    public DependencyNode getRoot()
088    {
089        return root;
090    }
091
092    /**
093     * Sets the root node of the dependency graph whose artifacts should be resolved. When this request is processed,
094     * the nodes of the given dependency graph will be updated to refer to the resolved artifacts. Eventually, either
095     * {@link #setRoot(DependencyNode)} or {@link #setCollectRequest(CollectRequest)} must be called to create a valid
096     * request.
097     * 
098     * @param root The root node of the dependency graph, may be {@code null}.
099     * @return This request for chaining, never {@code null}.
100     */
101    public DependencyRequest setRoot( DependencyNode root )
102    {
103        this.root = root;
104        return this;
105    }
106
107    /**
108     * Gets the collect request used to calculate the dependency graph whose artifacts should be resolved.
109     * 
110     * @return The collect request or {@code null} if none.
111     */
112    public CollectRequest getCollectRequest()
113    {
114        return collectRequest;
115    }
116
117    /**
118     * Sets the collect request used to calculate the dependency graph whose artifacts should be resolved. Eventually,
119     * either {@link #setRoot(DependencyNode)} or {@link #setCollectRequest(CollectRequest)} must be called to create a
120     * valid request. If this request is supplied with a dependency node via {@link #setRoot(DependencyNode)}, the
121     * collect request is ignored.
122     * 
123     * @param collectRequest The collect request, may be {@code null}.
124     * @return This request for chaining, never {@code null}.
125     */
126    public DependencyRequest setCollectRequest( CollectRequest collectRequest )
127    {
128        this.collectRequest = collectRequest;
129        return this;
130    }
131
132    /**
133     * Gets the resolution filter used to select which artifacts of the dependency graph should be resolved.
134     * 
135     * @return The resolution filter or {@code null} to resolve all artifacts of the dependency graph.
136     */
137    public DependencyFilter getFilter()
138    {
139        return filter;
140    }
141
142    /**
143     * Sets the resolution filter used to select which artifacts of the dependency graph should be resolved. For
144     * example, use this filter to restrict resolution to dependencies of a certain scope.
145     * 
146     * @param filter The resolution filter, may be {@code null} to resolve all artifacts of the dependency graph.
147     * @return This request for chaining, never {@code null}.
148     */
149    public DependencyRequest setFilter( DependencyFilter filter )
150    {
151        this.filter = filter;
152        return this;
153    }
154
155    /**
156     * Gets the trace information that describes the higher level request/operation in which this request is issued.
157     * 
158     * @return The trace information about the higher level operation or {@code null} if none.
159     */
160    public RequestTrace getTrace()
161    {
162        return trace;
163    }
164
165    /**
166     * Sets the trace information that describes the higher level request/operation in which this request is issued.
167     * 
168     * @param trace The trace information about the higher level operation, may be {@code null}.
169     * @return This request for chaining, never {@code null}.
170     */
171    public DependencyRequest setTrace( RequestTrace trace )
172    {
173        this.trace = trace;
174        return this;
175    }
176
177    @Override
178    public String toString()
179    {
180        if ( root != null )
181        {
182            return String.valueOf( root );
183        }
184        return String.valueOf( collectRequest );
185    }
186
187}