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