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