View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.eclipse.aether.collection;
20  
21  import java.util.ArrayList;
22  import java.util.Collections;
23  import java.util.List;
24  
25  import org.eclipse.aether.RepositorySystem;
26  import org.eclipse.aether.RequestTrace;
27  import org.eclipse.aether.artifact.Artifact;
28  import org.eclipse.aether.graph.Dependency;
29  import org.eclipse.aether.repository.RemoteRepository;
30  
31  /**
32   * A request to collect the transitive dependencies and to build a dependency graph from them. There are three ways to
33   * create a dependency graph. First, only the root dependency can be given. Second, a root dependency and direct
34   * dependencies can be specified in which case the specified direct dependencies are merged with the direct dependencies
35   * retrieved from the artifact descriptor of the root dependency. And last, only direct dependencies can be specified in
36   * which case the root node of the resulting graph has no associated dependency.
37   *
38   * @see RepositorySystem#collectDependencies(org.eclipse.aether.RepositorySystemSession, CollectRequest)
39   */
40  public final class CollectRequest {
41  
42      private Artifact rootArtifact;
43  
44      private Dependency root;
45  
46      private List<Dependency> dependencies = Collections.emptyList();
47  
48      private List<Dependency> managedDependencies = Collections.emptyList();
49  
50      private List<RemoteRepository> repositories = Collections.emptyList();
51  
52      private String context = "";
53  
54      private RequestTrace trace;
55  
56      /**
57       * Creates an uninitialized request.
58       */
59      public CollectRequest() {
60          // enables default constructor
61      }
62  
63      /**
64       * Creates a request with the specified properties.
65       *
66       * @param root The root dependency whose transitive dependencies should be collected, may be {@code null}.
67       * @param repositories The repositories to use for the collection, may be {@code null}.
68       */
69      public CollectRequest(Dependency root, List<RemoteRepository> repositories) {
70          setRoot(root);
71          setRepositories(repositories);
72      }
73  
74      /**
75       * Creates a new request with the specified properties.
76       *
77       * @param root The root dependency whose transitive dependencies should be collected, may be {@code null}.
78       * @param dependencies The direct dependencies to merge with the direct dependencies from the root dependency's
79       *            artifact descriptor.
80       * @param repositories The repositories to use for the collection, may be {@code null}.
81       */
82      public CollectRequest(Dependency root, List<Dependency> dependencies, List<RemoteRepository> repositories) {
83          setRoot(root);
84          setDependencies(dependencies);
85          setRepositories(repositories);
86      }
87  
88      /**
89       * Creates a new request with the specified properties.
90       *
91       * @param dependencies The direct dependencies of some imaginary root, may be {@code null}.
92       * @param managedDependencies The dependency management information to apply to the transitive dependencies, may be
93       *            {@code null}.
94       * @param repositories The repositories to use for the collection, may be {@code null}.
95       */
96      public CollectRequest(
97              List<Dependency> dependencies, List<Dependency> managedDependencies, List<RemoteRepository> repositories) {
98          setDependencies(dependencies);
99          setManagedDependencies(managedDependencies);
100         setRepositories(repositories);
101     }
102 
103     /**
104      * Gets the root artifact for the dependency graph.
105      *
106      * @return The root artifact for the dependency graph or {@code null} if none.
107      */
108     public Artifact getRootArtifact() {
109         return rootArtifact;
110     }
111 
112     /**
113      * Sets the root artifact for the dependency graph. This must not be confused with {@link #setRoot(Dependency)}: The
114      * root <em>dependency</em>, like any other specified dependency, will be subject to dependency
115      * collection/resolution, i.e. should have an artifact descriptor and a corresponding artifact file. The root
116      * <em>artifact</em> on the other hand is only used as a label for the root node of the graph in case no root
117      * dependency was specified. As such, the configured root artifact is ignored if {@link #getRoot()} does not return
118      * {@code null}.
119      *
120      * @param rootArtifact The root artifact for the dependency graph, may be {@code null}.
121      * @return This request for chaining, never {@code null}.
122      */
123     public CollectRequest setRootArtifact(Artifact rootArtifact) {
124         this.rootArtifact = rootArtifact;
125         return this;
126     }
127 
128     /**
129      * Gets the root dependency of the graph.
130      *
131      * @return The root dependency of the graph or {@code null} if none.
132      */
133     public Dependency getRoot() {
134         return root;
135     }
136 
137     /**
138      * Sets the root dependency of the graph.
139      *
140      * @param root The root dependency of the graph, may be {@code null}.
141      * @return This request for chaining, never {@code null}.
142      */
143     public CollectRequest setRoot(Dependency root) {
144         this.root = root;
145         return this;
146     }
147 
148     /**
149      * Gets the direct dependencies.
150      *
151      * @return The direct dependencies, never {@code null}.
152      */
153     public List<Dependency> getDependencies() {
154         return dependencies;
155     }
156 
157     /**
158      * Sets the direct dependencies. If both a root dependency and direct dependencies are given in the request, the
159      * direct dependencies from the request will be merged with the direct dependencies from the root dependency's
160      * artifact descriptor, giving higher priority to the dependencies from the request.
161      *
162      * @param dependencies The direct dependencies, may be {@code null}.
163      * @return This request for chaining, never {@code null}.
164      */
165     public CollectRequest setDependencies(List<Dependency> dependencies) {
166         if (dependencies == null) {
167             this.dependencies = Collections.emptyList();
168         } else {
169             this.dependencies = dependencies;
170         }
171         return this;
172     }
173 
174     /**
175      * Adds the specified direct dependency.
176      *
177      * @param dependency The dependency to add, may be {@code null}.
178      * @return This request for chaining, never {@code null}.
179      */
180     public CollectRequest addDependency(Dependency dependency) {
181         if (dependency != null) {
182             if (this.dependencies.isEmpty()) {
183                 this.dependencies = new ArrayList<>();
184             }
185             this.dependencies.add(dependency);
186         }
187         return this;
188     }
189 
190     /**
191      * Gets the dependency management to apply to transitive dependencies.
192      *
193      * @return The dependency management to apply to transitive dependencies, never {@code null}.
194      */
195     public List<Dependency> getManagedDependencies() {
196         return managedDependencies;
197     }
198 
199     /**
200      * Sets the dependency management to apply to transitive dependencies. To clarify, this management does not apply to
201      * the direct dependencies of the root node.
202      *
203      * @param managedDependencies The dependency management, may be {@code null}.
204      * @return This request for chaining, never {@code null}.
205      */
206     public CollectRequest setManagedDependencies(List<Dependency> managedDependencies) {
207         if (managedDependencies == null) {
208             this.managedDependencies = Collections.emptyList();
209         } else {
210             this.managedDependencies = managedDependencies;
211         }
212         return this;
213     }
214 
215     /**
216      * Adds the specified managed dependency.
217      *
218      * @param managedDependency The managed dependency to add, may be {@code null}.
219      * @return This request for chaining, never {@code null}.
220      */
221     public CollectRequest addManagedDependency(Dependency managedDependency) {
222         if (managedDependency != null) {
223             if (this.managedDependencies.isEmpty()) {
224                 this.managedDependencies = new ArrayList<>();
225             }
226             this.managedDependencies.add(managedDependency);
227         }
228         return this;
229     }
230 
231     /**
232      * Gets the repositories to use for the collection.
233      *
234      * @return The repositories to use for the collection, never {@code null}.
235      */
236     public List<RemoteRepository> getRepositories() {
237         return repositories;
238     }
239 
240     /**
241      * Sets the repositories to use for the collection.
242      *
243      * @param repositories The repositories to use for the collection, may be {@code null}.
244      * @return This request for chaining, never {@code null}.
245      */
246     public CollectRequest setRepositories(List<RemoteRepository> repositories) {
247         if (repositories == null) {
248             this.repositories = Collections.emptyList();
249         } else {
250             this.repositories = repositories;
251         }
252         return this;
253     }
254 
255     /**
256      * Adds the specified repository for collection.
257      *
258      * @param repository The repository to collect dependency information from, may be {@code null}.
259      * @return This request for chaining, never {@code null}.
260      */
261     public CollectRequest addRepository(RemoteRepository repository) {
262         if (repository != null) {
263             if (this.repositories.isEmpty()) {
264                 this.repositories = new ArrayList<>();
265             }
266             this.repositories.add(repository);
267         }
268         return this;
269     }
270 
271     /**
272      * Gets the context in which this request is made.
273      *
274      * @return The context, never {@code null}.
275      */
276     public String getRequestContext() {
277         return context;
278     }
279 
280     /**
281      * Sets the context in which this request is made.
282      *
283      * @param context The context, may be {@code null}.
284      * @return This request for chaining, never {@code null}.
285      */
286     public CollectRequest setRequestContext(String context) {
287         this.context = (context != null) ? context : "";
288         return this;
289     }
290 
291     /**
292      * Gets the trace information that describes the higher level request/operation in which this request is issued.
293      *
294      * @return The trace information about the higher level operation or {@code null} if none.
295      */
296     public RequestTrace getTrace() {
297         return trace;
298     }
299 
300     /**
301      * Sets the trace information that describes the higher level request/operation in which this request is issued.
302      *
303      * @param trace The trace information about the higher level operation, may be {@code null}.
304      * @return This request for chaining, never {@code null}.
305      */
306     public CollectRequest setTrace(RequestTrace trace) {
307         this.trace = trace;
308         return this;
309     }
310 
311     @Override
312     public String toString() {
313         return getRoot() + " -> " + getDependencies() + " < " + getRepositories();
314     }
315 }