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.apache.maven.api.services;
20  
21  import java.util.List;
22  
23  import org.apache.maven.api.Artifact;
24  import org.apache.maven.api.DependencyCoordinates;
25  import org.apache.maven.api.Node;
26  import org.apache.maven.api.PathScope;
27  import org.apache.maven.api.Project;
28  import org.apache.maven.api.Service;
29  import org.apache.maven.api.Session;
30  import org.apache.maven.api.annotations.Experimental;
31  import org.apache.maven.api.annotations.Nonnull;
32  
33  /**
34   * Collects, flattens and resolves dependencies.
35   */
36  @Experimental
37  public interface DependencyResolver extends Service {
38  
39      /**
40       * Collects the transitive dependencies of some artifacts and builds a dependency graph. Note that this operation is
41       * only concerned about determining the coordinates of the transitive dependencies and does not actually resolve the
42       * artifact files.
43       *
44       * @param session the {@link Session}, must not be {@code null}
45       * @param root the Maven Dependency, must not be {@code null}
46       * @return the collection result, never {@code null}
47       * @throws DependencyResolverException if the dependency tree could not be built
48       * @throws IllegalArgumentException if an argument is null or invalid
49       * @see #collect(DependencyResolverRequest)
50       */
51      @Nonnull
52      default DependencyResolverResult collect(@Nonnull Session session, @Nonnull DependencyCoordinates root) {
53          return collect(DependencyResolverRequest.build(session, DependencyResolverRequest.RequestType.COLLECT, root));
54      }
55  
56      /**
57       * Collects the transitive dependencies of some artifacts and builds a dependency graph. Note that this operation is
58       * only concerned about determining the coordinates of the transitive dependencies and does not actually resolve the
59       * artifact files.
60       *
61       * @param session the {@link Session}, must not be {@code null}
62       * @param project the {@link Project}, must not be {@code null}
63       * @return the collection result, never {@code null}
64       * @throws DependencyResolverException if the dependency tree could not be built
65       * @throws IllegalArgumentException if an argument is null or invalid
66       * @see #collect(DependencyResolverRequest)
67       */
68      @Nonnull
69      default DependencyResolverResult collect(@Nonnull Session session, @Nonnull Project project) {
70          return collect(
71                  DependencyResolverRequest.build(session, DependencyResolverRequest.RequestType.COLLECT, project));
72      }
73  
74      /**
75       * Collects the transitive dependencies of some artifacts and builds a dependency graph. Note that this operation is
76       * only concerned about determining the coordinates of the transitive dependencies and does not actually resolve the
77       * artifact files.
78       *
79       * @param session the {@link Session}, must not be {@code null}
80       * @param artifact the {@link Artifact}, must not be {@code null}
81       * @return the collection result, never {@code null}
82       * @throws DependencyResolverException if the dependency tree could not be built
83       * @throws IllegalArgumentException if an argument is null or invalid
84       * @see #collect(DependencyResolverRequest)
85       */
86      @Nonnull
87      default DependencyResolverResult collect(@Nonnull Session session, @Nonnull Artifact artifact) {
88          return collect(
89                  DependencyResolverRequest.build(session, DependencyResolverRequest.RequestType.COLLECT, artifact));
90      }
91  
92      /**
93       * Collects the transitive dependencies and builds a dependency graph.
94       * Note that this operation is only concerned about determining the coordinates of the
95       * transitive dependencies and does not actually resolve the artifact files.
96       *
97       * @param request the dependency collection request, must not be {@code null}
98       * @return the collection result, never {@code null}
99       * @throws DependencyResolverException if the dependency tree could not be built
100      * @throws IllegalArgumentException if an argument is null or invalid
101      *
102      * @see DependencyResolver#collect(Session, Project)
103      * @see DependencyResolver#collect(Session, DependencyCoordinates)
104      * @see DependencyResolver#collect(Session, Artifact)
105      */
106     @Nonnull
107     default DependencyResolverResult collect(@Nonnull DependencyResolverRequest request) {
108         if (request.getRequestType() != DependencyResolverRequest.RequestType.COLLECT) {
109             throw new IllegalArgumentException("requestType should be COLLECT when calling collect()");
110         }
111         return resolve(request);
112     }
113 
114     /**
115      * Flattens a list of nodes.
116      *
117      * @param session
118      * @param node
119      * @param scope
120      * @return
121      * @throws DependencyResolverException
122      */
123     List<Node> flatten(Session session, Node node, PathScope scope) throws DependencyResolverException;
124 
125     @Nonnull
126     default DependencyResolverResult flatten(@Nonnull Session session, @Nonnull Project project) {
127         return flatten(
128                 DependencyResolverRequest.build(session, DependencyResolverRequest.RequestType.FLATTEN, project));
129     }
130 
131     @Nonnull
132     default DependencyResolverResult flatten(
133             @Nonnull Session session, @Nonnull Project project, @Nonnull PathScope scope) {
134         return flatten(DependencyResolverRequest.build(
135                 session, DependencyResolverRequest.RequestType.FLATTEN, project, scope));
136     }
137 
138     @Nonnull
139     default DependencyResolverResult flatten(@Nonnull DependencyResolverRequest request) {
140         if (request.getRequestType() != DependencyResolverRequest.RequestType.FLATTEN) {
141             throw new IllegalArgumentException("requestType should be FLATTEN when calling flatten()");
142         }
143         return resolve(request);
144     }
145 
146     @Nonnull
147     default DependencyResolverResult resolve(@Nonnull Session session, @Nonnull Project project) {
148         return resolve(
149                 DependencyResolverRequest.build(session, DependencyResolverRequest.RequestType.RESOLVE, project));
150     }
151 
152     @Nonnull
153     default DependencyResolverResult resolve(
154             @Nonnull Session session, @Nonnull Project project, @Nonnull PathScope scope) {
155         return resolve(DependencyResolverRequest.build(
156                 session, DependencyResolverRequest.RequestType.RESOLVE, project, scope));
157     }
158 
159     @Nonnull
160     default DependencyResolverResult resolve(@Nonnull Session session, @Nonnull DependencyCoordinates dependency) {
161         return resolve(
162                 DependencyResolverRequest.build(session, DependencyResolverRequest.RequestType.RESOLVE, dependency));
163     }
164 
165     @Nonnull
166     default DependencyResolverResult resolve(
167             @Nonnull Session session, @Nonnull DependencyCoordinates dependency, @Nonnull PathScope scope) {
168         return resolve(DependencyResolverRequest.build(
169                 session, DependencyResolverRequest.RequestType.RESOLVE, dependency, scope));
170     }
171 
172     @Nonnull
173     default DependencyResolverResult resolve(
174             @Nonnull Session session, @Nonnull List<DependencyCoordinates> dependencies) {
175         return resolve(
176                 DependencyResolverRequest.build(session, DependencyResolverRequest.RequestType.RESOLVE, dependencies));
177     }
178 
179     @Nonnull
180     default DependencyResolverResult resolve(
181             @Nonnull Session session, @Nonnull List<DependencyCoordinates> dependencies, @Nonnull PathScope scope) {
182         return resolve(DependencyResolverRequest.build(
183                 session, DependencyResolverRequest.RequestType.RESOLVE, dependencies, scope));
184     }
185 
186     /**
187      * This method collects, flattens and resolves the dependencies.
188      *
189      * @param request the request to resolve
190      * @return the result of the resolution
191      * @throws DependencyResolverException
192      * @throws ArtifactResolverException
193      *
194      * @see DependencyResolver#collect(DependencyResolverRequest)
195      * @see #flatten(Session, Node, PathScope)
196      * @see ArtifactResolver#resolve(ArtifactResolverRequest)
197      */
198     DependencyResolverResult resolve(DependencyResolverRequest request)
199             throws DependencyResolverException, ArtifactResolverException;
200 }