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