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;
20
21 import java.nio.file.Path;
22 import java.util.Collection;
23 import java.util.List;
24 import java.util.Map;
25 import java.util.NoSuchElementException;
26 import java.util.Optional;
27
28 import org.apache.maven.api.annotations.Experimental;
29 import org.apache.maven.api.annotations.Nonnull;
30 import org.apache.maven.api.annotations.Nullable;
31 import org.apache.maven.api.annotations.ThreadSafe;
32 import org.apache.maven.api.model.Repository;
33 import org.apache.maven.api.services.ArtifactCoordinatesFactory;
34 import org.apache.maven.api.services.DependencyCoordinatesFactory;
35 import org.apache.maven.api.services.VersionResolverException;
36 import org.apache.maven.api.settings.Settings;
37
38 /**
39 * The session to install / deploy / resolve artifacts and dependencies.
40 *
41 * TODO: add request trace so that requests can be linked together and through the resolver
42 * TODO: add a Request interface holding session + parent request
43 *
44 * @since 4.0.0
45 */
46 @Experimental
47 @ThreadSafe
48 public interface Session extends ProtoSession {
49
50 /**
51 * Returns the current maven version.
52 *
53 * @return the maven version, never {@code null}
54 */
55 @Nonnull
56 Version getMavenVersion();
57
58 /**
59 * Retrieves the settings for the current session.
60 *
61 * @return the settings instance
62 */
63 @Nonnull
64 Settings getSettings();
65
66 /**
67 * Retrieves the local repository associated with this session.
68 *
69 * @return the local repository instance
70 */
71 @Nonnull
72 LocalRepository getLocalRepository();
73
74 /**
75 * Retrieves a list of remote repositories associated with this session.
76 *
77 * @return a list of remote repositories
78 */
79 @Nonnull
80 List<RemoteRepository> getRemoteRepositories();
81
82 /**
83 * Retrieves the session data associated with this session.
84 *
85 * @return the session data, never {@code null}
86 */
87 @Nonnull
88 SessionData getData();
89
90 /**
91 * Each invocation computes a new map of effective properties. To be used in interpolation.
92 * <p>
93 * Effective properties are computed from system, user and optionally project properties, layered with
94 * defined precedence onto each other to achieve proper precedence. Precedence is defined as:
95 * <ul>
96 * <li>System properties (lowest precedence)</li>
97 * <li>Project properties (optional)</li>
98 * <li>User properties (highest precedence)</li>
99 * </ul>
100 * Note: Project properties contains properties injected from profiles, if applicable. Their precedence is
101 * {@code profile > project}, hence active profile property may override project property.
102 * <p>
103 * The caller of this method should decide whether there is a project in scope (hence, a project instance
104 * needs to be passed) or not.
105 *
106 * @param project {@link Project} or {@code null}.
107 * @return the effective properties, never {@code null}
108 */
109 @Nonnull
110 Map<String, String> getEffectiveProperties(@Nullable Project project);
111
112 /**
113 * Returns the degree of concurrency for the build.
114 *
115 * @return the degree of concurrency
116 */
117 int getDegreeOfConcurrency();
118
119 /**
120 * Retrieves a list of projects associated with the session.
121 *
122 * @return a list of projects, never {@code null}
123 */
124 @Nonnull
125 List<Project> getProjects();
126
127 /**
128 * Returns the plugin context for mojo being executed and the specified
129 * {@link Project}, never returns {@code null} as if context not present, creates it.
130 *
131 * <strong>Implementation note:</strong> while this method return type is {@link Map}, the
132 * returned map instance implements {@link java.util.concurrent.ConcurrentMap} as well.
133 *
134 * @throws org.apache.maven.api.services.MavenException if not called from the within a mojo execution
135 */
136 @Nonnull
137 Map<String, Object> getPluginContext(@Nonnull Project project);
138
139 /**
140 * Retrieves the service for the interface
141 *
142 * @throws NoSuchElementException if the service could not be found
143 */
144 @Nonnull
145 <T extends Service> T getService(@Nonnull Class<T> clazz);
146
147 /**
148 * Creates a derived session using the given local repository.
149 *
150 * @param localRepository the new local repository
151 * @return the derived session
152 * @throws NullPointerException if {@code localRepository} is null
153 */
154 @Nonnull
155 Session withLocalRepository(@Nonnull LocalRepository localRepository);
156
157 /**
158 * Creates a derived session using the given remote repositories.
159 *
160 * @param repositories the new list of remote repositories
161 * @return the derived session
162 * @throws NullPointerException if {@code repositories} is null
163 */
164 @Nonnull
165 Session withRemoteRepositories(@Nonnull List<RemoteRepository> repositories);
166
167 /**
168 * Register the given listener which will receive all events.
169 *
170 * @param listener the listener to register
171 * @throws NullPointerException if {@code listener} is null
172 */
173 void registerListener(@Nonnull Listener listener);
174
175 /**
176 * Unregisters a previously registered listener.
177 *
178 * @param listener the listener to unregister
179 * @throws NullPointerException if {@code listener} is null
180 */
181 void unregisterListener(@Nonnull Listener listener);
182
183 /**
184 * Returns the list of registered listeners.
185 *
186 * @return an immutable collection of listeners, never {@code null}
187 */
188 @Nonnull
189 Collection<Listener> getListeners();
190
191 /**
192 * Shortcut for {@code getService(RepositoryFactory.class).createLocal(...)}.
193 *
194 * @param path location of the local repository to create
195 * @return cache of artifacts downloaded from a remote repository or built locally
196 *
197 * @see org.apache.maven.api.services.RepositoryFactory#createLocal(Path)
198 */
199 @Nonnull
200 LocalRepository createLocalRepository(@Nonnull Path path);
201
202 /**
203 * Shortcut for {@code getService(RepositoryFactory.class).createRemote(...)}.
204 *
205 * @param id identifier of the remote repository to create
206 * @param url location of the remote repository
207 * @return remote repository that can be used to download or upload artifacts
208 *
209 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(String, String)
210 */
211 @Nonnull
212 RemoteRepository createRemoteRepository(@Nonnull String id, @Nonnull String url);
213
214 /**
215 * Shortcut for {@code getService(RepositoryFactory.class).createRemote(...)}.
216 *
217 * @param repository information needed for establishing connections with remote repository
218 * @return remote repository that can be used to download or upload artifacts
219 *
220 * @see org.apache.maven.api.services.RepositoryFactory#createRemote(Repository)
221 */
222 @Nonnull
223 RemoteRepository createRemoteRepository(@Nonnull Repository repository);
224
225 /**
226 * Creates a coordinates out of string that is formatted like:
227 * {@code <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>}.
228 * <p>
229 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
230 *
231 * @param coordsString the string having "standard" coordinates.
232 * @return coordinates used to point to the artifact
233 *
234 * @see ArtifactCoordinatesFactory#create(Session, String)
235 */
236 @Nonnull
237 ArtifactCoordinates createArtifactCoordinates(@Nonnull String coordsString);
238
239 /**
240 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
241 *
242 * @param groupId the group identifier, or {@code null} is unspecified
243 * @param artifactId the artifact identifier, or {@code null} is unspecified
244 * @param version the artifact version, or {@code null} is unspecified
245 * @param extension the artifact extension, or {@code null} is unspecified
246 * @return coordinates used to point to the artifact
247 *
248 * @see ArtifactCoordinatesFactory#create(Session, String, String, String, String)
249 */
250 @Nonnull
251 ArtifactCoordinates createArtifactCoordinates(String groupId, String artifactId, String version, String extension);
252
253 /**
254 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
255 *
256 * @param groupId the group identifier, or {@code null} is unspecified
257 * @param artifactId the artifact identifier, or {@code null} is unspecified
258 * @param version the artifact version, or {@code null} is unspecified
259 * @param classifier the artifact classifier, or {@code null} is unspecified
260 * @param extension the artifact extension, or {@code null} is unspecified
261 * @param type the artifact type, or {@code null} is unspecified
262 * @return coordinates used to point to the artifact
263 *
264 * @see ArtifactCoordinatesFactory#create(Session, String, String, String, String, String, String)
265 */
266 @Nonnull
267 ArtifactCoordinates createArtifactCoordinates(
268 String groupId, String artifactId, String version, String classifier, String extension, String type);
269
270 /**
271 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
272 *
273 * @param artifact artifact from which to get coordinates
274 * @return coordinates used to point to the artifact
275 *
276 * @see ArtifactCoordinatesFactory#create(Session, String, String, String, String, String, String)
277 */
278 @Nonnull
279 ArtifactCoordinates createArtifactCoordinates(@Nonnull Artifact artifact);
280
281 /**
282 * Shortcut for {@code getService(DependencyFactory.class).create(...)}.
283 *
284 * @param coordinates artifact coordinates to get as a dependency coordinates
285 * @return dependency coordinates for the given artifact
286 *
287 * @see DependencyCoordinatesFactory#create(Session, ArtifactCoordinates)
288 */
289 @Nonnull
290 DependencyCoordinates createDependencyCoordinates(@Nonnull ArtifactCoordinates coordinates);
291
292 /**
293 * Shortcut for {@code getService(DependencyFactory.class).create(...)}.
294 *
295 * @param dependency dependency for which to get the coordinates
296 * @return coordinates for the given dependency
297 *
298 * @see DependencyCoordinatesFactory#create(Session, Dependency)
299 */
300 @Nonnull
301 DependencyCoordinates createDependencyCoordinates(@Nonnull Dependency dependency);
302
303 /**
304 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
305 *
306 * @param groupId the group identifier, or {@code null} is unspecified
307 * @param artifactId the artifact identifier, or {@code null} is unspecified
308 * @param version the artifact version, or {@code null} is unspecified
309 * @param extension the artifact extension, or {@code null} is unspecified
310 * @return artifact with the given coordinates
311 *
312 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)
313 */
314 @Nonnull
315 Artifact createArtifact(String groupId, String artifactId, String version, String extension);
316
317 /**
318 * Shortcut for {@code getService(ArtifactFactory.class).create(...)}.
319 *
320 * @param groupId the group identifier, or {@code null} is unspecified
321 * @param artifactId the artifact identifier, or {@code null} is unspecified
322 * @param version the artifact version, or {@code null} is unspecified
323 * @param classifier the artifact classifier, or {@code null} is unspecified
324 * @param extension the artifact extension, or {@code null} is unspecified
325 * @param type the artifact type, or {@code null} is unspecified
326 * @return artifact with the given coordinates
327 *
328 * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String, String, String)
329 */
330 @Nonnull
331 Artifact createArtifact(
332 String groupId, String artifactId, String version, String classifier, String extension, String type);
333
334 /**
335 * Shortcut for {@code getService(ArtifactFactory.class).createProduced(...)}.
336 *
337 * @param groupId the group identifier, or {@code null} is unspecified
338 * @param artifactId the artifact identifier, or {@code null} is unspecified
339 * @param version the artifact version, or {@code null} is unspecified
340 * @param extension the artifact extension, or {@code null} is unspecified
341 * @return artifact with the given coordinates
342 *
343 * @see org.apache.maven.api.services.ArtifactFactory#createProduced(Session, String, String, String, String)
344 */
345 @Nonnull
346 ProducedArtifact createProducedArtifact(String groupId, String artifactId, String version, String extension);
347
348 /**
349 * Shortcut for {@code getService(ArtifactFactory.class).createProduced(...)}.
350 *
351 * @param groupId the group identifier, or {@code null} is unspecified
352 * @param artifactId the artifact identifier, or {@code null} is unspecified
353 * @param version the artifact version, or {@code null} is unspecified
354 * @param classifier the artifact classifier, or {@code null} is unspecified
355 * @param extension the artifact extension, or {@code null} is unspecified
356 * @param type the artifact type, or {@code null} is unspecified
357 * @return artifact with the given coordinates
358 *
359 * @see org.apache.maven.api.services.ArtifactFactory#createProduced(Session, String, String, String, String, String, String)
360 */
361 @Nonnull
362 ProducedArtifact createProducedArtifact(
363 String groupId, String artifactId, String version, String classifier, String extension, String type);
364
365 /**
366 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
367 *
368 * @param coordinates coordinates of the artifact to resolve
369 * @return requested artifact together with the path to its file
370 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
371 *
372 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
373 */
374 @Nonnull
375 DownloadedArtifact resolveArtifact(@Nonnull ArtifactCoordinates coordinates);
376
377 /**
378 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
379 *
380 * @param coordinates coordinates of the artifact to resolve
381 * @param repositories repositories to use, if {@code null}, the session repositories are used
382 * @return requested artifact together with the path to its file
383 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
384 *
385 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
386 */
387 @Nonnull
388 DownloadedArtifact resolveArtifact(@Nonnull ArtifactCoordinates coordinates, List<RemoteRepository> repositories);
389
390 /**
391 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
392 *
393 * @param coordinates coordinates of all artifacts to resolve
394 * @return requested artifacts together with the paths to their files
395 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
396 *
397 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
398 */
399 @Nonnull
400 Collection<DownloadedArtifact> resolveArtifacts(@Nonnull ArtifactCoordinates... coordinates);
401
402 /**
403 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
404 *
405 * @param coordinates coordinates of all artifacts to resolve
406 * @return requested artifacts together with the paths to their files
407 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
408 *
409 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
410 */
411 @Nonnull
412 Collection<DownloadedArtifact> resolveArtifacts(@Nonnull Collection<? extends ArtifactCoordinates> coordinates);
413
414 /**
415 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
416 *
417 * @param coordinates coordinates of all artifacts to resolve
418 * @param repositories repositories to use, if {@code null}, the session repositories are used
419 * @return requested artifacts together with the paths to their files
420 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
421 *
422 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
423 */
424 @Nonnull
425 Collection<DownloadedArtifact> resolveArtifacts(
426 @Nonnull Collection<? extends ArtifactCoordinates> coordinates,
427 @Nullable List<RemoteRepository> repositories);
428
429 /**
430 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
431 *
432 * @param artifact the artifact to resolve
433 * @return requested artifact together with the path to its file
434 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
435 *
436 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
437 */
438 @Nonnull
439 DownloadedArtifact resolveArtifact(@Nonnull Artifact artifact);
440
441 /**
442 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
443 *
444 * @param artifact the artifact to resolve
445 * @param repositories repositories to use, if {@code null}, the session repositories are used
446 * @return requested artifact together with the path to its file
447 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
448 *
449 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
450 */
451 @Nonnull
452 DownloadedArtifact resolveArtifact(@Nonnull Artifact artifact, @Nullable List<RemoteRepository> repositories);
453
454 /**
455 * Shortcut for {@code getService(ArtifactResolver.class).resolve(...)}.
456 *
457 * @param artifacts all artifacts to resolve
458 * @return requested artifacts together with the paths to their files
459 * @throws org.apache.maven.api.services.ArtifactResolverException if the artifact resolution failed
460 *
461 * @see org.apache.maven.api.services.ArtifactResolver#resolve(Session, Collection)
462 */
463 @Nonnull
464 Collection<DownloadedArtifact> resolveArtifacts(@Nonnull Artifact... artifacts);
465
466 /**
467 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}.
468 *
469 * @param artifacts the artifacts to install
470 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
471 *
472 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
473 */
474 void installArtifacts(@Nonnull ProducedArtifact... artifacts);
475
476 /**
477 * Shortcut for {@code getService(ArtifactInstaller.class).install(...)}.
478 *
479 * @param artifacts the artifacts to install
480 * @throws org.apache.maven.api.services.ArtifactInstallerException if the artifacts installation failed
481 *
482 * @see org.apache.maven.api.services.ArtifactInstaller#install(Session, Collection)
483 */
484 void installArtifacts(@Nonnull Collection<ProducedArtifact> artifacts);
485
486 /**
487 * Shortcut for {@code getService(ArtifactDeployer.class).deploy(...)}.
488 *
489 * @param repository the repository where to deploy artifacts
490 * @param artifacts the artifacts to deploy
491 * @throws org.apache.maven.api.services.ArtifactDeployerException if the artifacts deployment failed
492 *
493 * @see org.apache.maven.api.services.ArtifactDeployer#deploy(Session, RemoteRepository, Collection)
494 */
495 void deployArtifact(@Nonnull RemoteRepository repository, @Nonnull ProducedArtifact... artifacts);
496
497 /**
498 * Shortcut for {@code getService(ArtifactManager.class).setPath(...)}.
499 *
500 * @param artifact the artifact for which to associate a path
501 * @param path path to associate to the given artifact
502 *
503 * @see org.apache.maven.api.services.ArtifactManager#setPath(ProducedArtifact, Path)
504 */
505 void setArtifactPath(@Nonnull ProducedArtifact artifact, @Nonnull Path path);
506
507 /**
508 * Shortcut for {@code getService(ArtifactManager.class).getPath(...)}.
509 *
510 * @param artifact the artifact for which to get a path
511 * @return path associated to the given artifact
512 *
513 * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
514 */
515 @Nonnull
516 Optional<Path> getArtifactPath(@Nonnull Artifact artifact);
517
518 /**
519 * Gets the relative path for a locally installed artifact. Note that the artifact need not actually exist yet at
520 * the returned location, the path merely indicates where the artifact would eventually be stored.
521 * <p>
522 * Shortcut for {@code getService(LocalArtifactManager.class).getPathForLocalArtitact(...)}.
523 *
524 * @param artifact the artifact for which to get a local path
525 * @return local path associated to the given artifact, or {@code null} if none
526 *
527 * @see org.apache.maven.api.services.LocalRepositoryManager#getPathForLocalArtifact(Session, LocalRepository, Artifact)
528 */
529 Path getPathForLocalArtifact(@Nonnull Artifact artifact);
530
531 /**
532 * Gets the relative path for an artifact cached from a remote repository.
533 * Note that the artifact need not actually exist yet at the returned location,
534 * the path merely indicates where the artifact would eventually be stored.
535 * <p>
536 * Shortcut for {@code getService(LocalArtifactManager.class).getPathForRemoteArtifact(...)}.
537 *
538 * @param remote the repository from where artifacts are downloaded
539 * @param artifact the artifact for which to get a path
540 * @return path associated to the given artifact
541 *
542 * @see org.apache.maven.api.services.LocalRepositoryManager#getPathForRemoteArtifact(Session, LocalRepository, RemoteRepository, Artifact)
543 */
544 @Nonnull
545 Path getPathForRemoteArtifact(@Nonnull RemoteRepository remote, @Nonnull Artifact artifact);
546
547 /**
548 * Checks whether a given artifact version is considered a {@code SNAPSHOT} or not.
549 * <p>
550 * Shortcut for {@code getService(ArtifactManager.class).isSnapshot(...)}.
551 * <p>
552 * In case there is {@link Artifact} in scope, the recommended way to perform this check is
553 * use of {@link Artifact#isSnapshot()} instead.
554 *
555 * @param version artifact version
556 * @return whether the given version is a snapshot
557 *
558 * @see org.apache.maven.api.services.VersionParser#isSnapshot(String)
559 */
560 boolean isVersionSnapshot(@Nonnull String version);
561
562 /**
563 * Shortcut for {@code getService(DependencyResolver.class).collect(...)}
564 *
565 * @param artifact artifact for which to get the dependencies, including transitive ones
566 * @param scope the {link PathScope} to collect dependencies, must not be {@code null}
567 * @return root node of the dependency graph for the given artifact
568 *
569 * @see org.apache.maven.api.services.DependencyResolver#collect(Session, Artifact, PathScope)
570 * @throws org.apache.maven.api.services.DependencyResolverException if the dependency collection failed
571 */
572 @Nonnull
573 Node collectDependencies(@Nonnull Artifact artifact, @Nonnull PathScope scope);
574
575 /**
576 * Shortcut for {@code getService(DependencyResolver.class).collect(...)}
577 *
578 * @param project project for which to get the dependencies, including transitive ones
579 * @param scope the {link PathScope} to collect dependencies, must not be {@code null}
580 * @return root node of the dependency graph for the given project
581 *
582 * @see org.apache.maven.api.services.DependencyResolver#collect(Session, Project, PathScope)
583 * @throws org.apache.maven.api.services.DependencyResolverException if the dependency collection failed
584 */
585 @Nonnull
586 Node collectDependencies(@Nonnull Project project, @Nonnull PathScope scope);
587
588 /**
589 * Collects the transitive dependencies of some artifacts and builds a dependency graph. Note that this operation is
590 * only concerned about determining the coordinates of the transitive dependencies and does not actually resolve the
591 * artifact files.
592 * <p>
593 * Shortcut for {@code getService(DependencyResolver.class).resolve(...)}
594 *
595 * @param dependency dependency for which to get transitive dependencies
596 * @param scope the {link PathScope} to collect dependencies, must not be {@code null}
597 * @return root node of the dependency graph for the given artifact
598 *
599 * @see org.apache.maven.api.services.DependencyResolver#collect(Session, DependencyCoordinates, PathScope)
600 * @throws org.apache.maven.api.services.DependencyResolverException if the dependency collection failed
601 */
602 @Nonnull
603 Node collectDependencies(@Nonnull DependencyCoordinates dependency, @Nonnull PathScope scope);
604
605 /**
606 * Shortcut for {@code getService(DependencyResolver.class).flatten(...)}.
607 *
608 * @param node node for which to get a flattened list
609 * @param scope build path scope (main compile, test compile, etc.) of desired nodes
610 * @return flattened list of node with the given build path scope
611 * @throws org.apache.maven.api.services.DependencyResolverException if the dependency flattening failed
612 *
613 * @see org.apache.maven.api.services.DependencyResolver#flatten(Session, Node, PathScope)
614 */
615 @Nonnull
616 List<Node> flattenDependencies(@Nonnull Node node, @Nonnull PathScope scope);
617
618 /**
619 * Shortcut for {@code getService(DependencyResolver.class).resolve(...).getPaths()}.
620 *
621 * @param dependencyCoordinates coordinates of the dependency for which to get the paths
622 * @return paths to the transitive dependencies of the given dependency
623 *
624 * @see org.apache.maven.api.services.DependencyResolver#resolve(Session, DependencyCoordinates)
625 */
626 @Nonnull
627 List<Path> resolveDependencies(@Nonnull DependencyCoordinates dependencyCoordinates);
628
629 /**
630 * Shortcut for {@code getService(DependencyResolver.class).resolve(...).getPaths()}.
631 *
632 * @param dependencyCoordinates coordinates of all dependency for which to get the paths
633 * @return paths to the transitive dependencies of the given dependencies
634 *
635 * @see org.apache.maven.api.services.DependencyResolver#resolve(Session, List)
636 */
637 @Nonnull
638 List<Path> resolveDependencies(@Nonnull List<DependencyCoordinates> dependencyCoordinates);
639
640 /**
641 * Shortcut for {@code getService(DependencyResolver.class).resolve(...).getPaths()}.
642 *
643 * @param project the project for which to get dependencies
644 * @param scope build path scope (main compile, test compile, etc.) of desired paths
645 * @return paths to the transitive dependencies of the given project
646 *
647 * @see org.apache.maven.api.services.DependencyResolver#resolve(Session, Project, PathScope)
648 */
649 @Nonnull
650 List<Path> resolveDependencies(@Nonnull Project project, @Nonnull PathScope scope);
651
652 /**
653 * Shortcut for {@code getService(DependencyResolver.class).resolve(...).getDispatchedPaths()}.
654 *
655 * @param dependencyCoordinates coordinates of the dependency for which to get the paths
656 * @param scope build path scope (main compile, test compile, etc.) of desired paths
657 * @param desiredTypes the type of paths to include in the result
658 * @return paths to the transitive dependencies of the given project
659 *
660 * @see org.apache.maven.api.services.DependencyResolver#resolve(Session, Project, PathScope)
661 */
662 @Nonnull
663 Map<PathType, List<Path>> resolveDependencies(
664 @Nonnull DependencyCoordinates dependencyCoordinates,
665 @Nonnull PathScope scope,
666 @Nonnull Collection<PathType> desiredTypes);
667
668 /**
669 * Shortcut for {@code getService(DependencyResolver.class).resolve(...).getDispatchedPaths()}.
670 *
671 * @param project the project for which to get dependencies
672 * @param scope build path scope (main compile, test compile, etc.) of desired paths
673 * @param desiredTypes the type of paths to include in the result
674 * @return paths to the transitive dependencies of the given project
675 *
676 * @see org.apache.maven.api.services.DependencyResolver#resolve(Session, Project, PathScope)
677 */
678 @Nonnull
679 Map<PathType, List<Path>> resolveDependencies(
680 @Nonnull Project project, @Nonnull PathScope scope, @Nonnull Collection<PathType> desiredTypes);
681
682 /**
683 * Resolves an artifact's meta version (if any) to a concrete version.
684 * For example, resolves "1.0-SNAPSHOT" to "1.0-20090208.132618-23".
685 * <p>
686 * Shortcut for {@code getService(VersionResolver.class).resolve(...)}
687 *
688 * @param artifact the artifact for which to resolve the version
689 * @return resolved version of the given artifact
690 * @throws org.apache.maven.api.services.VersionResolverException if the resolution failed
691 *
692 * @see org.apache.maven.api.services.VersionResolver#resolve(Session, ArtifactCoordinates) (String)
693 */
694 @Nonnull
695 Version resolveVersion(@Nonnull ArtifactCoordinates artifact) throws VersionResolverException;
696
697 /**
698 * Expands a version range to a list of matching versions, in ascending order.
699 * For example, resolves "[3.8,4.0)" to "3.8", "3.8.1", "3.8.2".
700 * The returned list of versions is only dependent on the configured repositories and their contents.
701 * The supplied request may also refer to a single concrete version rather than a version range.
702 * In this case though, the result contains simply the (parsed) input version, regardless of the
703 * repositories and their contents.
704 *
705 * @param artifact the artifact for which to resolve the versions
706 * @return a list of resolved {@code Version}s.
707 * @throws org.apache.maven.api.services.VersionRangeResolverException if the resolution failed
708 * @see org.apache.maven.api.services.VersionRangeResolver#resolve(Session, ArtifactCoordinates) (String)
709 */
710 @Nonnull
711 List<Version> resolveVersionRange(@Nonnull ArtifactCoordinates artifact) throws VersionResolverException;
712
713 /**
714 * Expands a version range to a list of matching versions, in ascending order.
715 * For example, resolves "[3.8,4.0)" to "3.8", "3.8.1", "3.8.2".
716 * The returned list of versions is only dependent on the configured repositories and their contents.
717 * The supplied request may also refer to a single concrete version rather than a version range.
718 * In this case though, the result contains simply the (parsed) input version, regardless of the
719 * repositories and their contents.
720 *
721 * @param artifact the artifact for which to resolve the versions
722 * @param repositories the repositories to use, or the session repositories if {@code null}
723 * @return a list of resolved {@code Version}s.
724 * @throws org.apache.maven.api.services.VersionRangeResolverException if the resolution failed
725 * @see org.apache.maven.api.services.VersionRangeResolver#resolve(Session, ArtifactCoordinates) (String)
726 */
727 @Nonnull
728 List<Version> resolveVersionRange(@Nonnull ArtifactCoordinates artifact, List<RemoteRepository> repositories)
729 throws VersionResolverException;
730
731 /**
732 * Parses the specified version string, for example "1.0".
733 * <p>
734 * Shortcut for {@code getService(VersionParser.class).parseVersion(...)}.
735 *
736 * @param version the version string to parse
737 * @return the version parsed from the given string
738 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
739 * @see org.apache.maven.api.services.VersionParser#parseVersion(String)
740 */
741 @Nonnull
742 Version parseVersion(@Nonnull String version);
743
744 /**
745 * Parses the specified version range specification, for example "[1.0,2.0)".
746 * <p>
747 * Shortcut for {@code getService(VersionParser.class).parseVersionRange(...)}.
748 *
749 * @param versionRange the version string to parse
750 * @return the version range parsed from the given string
751 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
752 * @see org.apache.maven.api.services.VersionParser#parseVersionRange(String)
753 */
754 @Nonnull
755 VersionRange parseVersionRange(@Nonnull String versionRange);
756
757 /**
758 * Parses the specified version constraint specification, for example "1.0" or "[1.0,2.0)".
759 * <p>
760 * Shortcut for {@code getService(VersionParser.class).parseVersionConstraint(...)}.
761 *
762 * @param versionConstraint the version string to parse
763 * @return the version constraint parsed from the given string
764 * @throws org.apache.maven.api.services.VersionParserException if the parsing failed
765 * @see org.apache.maven.api.services.VersionParser#parseVersionConstraint(String)
766 */
767 @Nonnull
768 VersionConstraint parseVersionConstraint(@Nonnull String versionConstraint);
769
770 /**
771 * Obtain the {@link Type} from the specified {@code id}.
772 * <p>
773 * Shortcut for {@code getService(TypeRegistry.class).require(...)}.
774 *
775 * @see org.apache.maven.api.services.TypeRegistry#require(String)
776 */
777 @Nonnull
778 Type requireType(@Nonnull String id);
779
780 /**
781 * Obtain the {@link Language} from the specified {@code id}.
782 * <p>
783 * Shortcut for {@code getService(LanguageRegistry.class).require(...)}.
784 *
785 * @see org.apache.maven.api.services.LanguageRegistry#require(String)
786 */
787 @Nonnull
788 Language requireLanguage(@Nonnull String id);
789
790 /**
791 * Obtain the {@link Packaging} from the specified {@code id}.
792 * <p>
793 * Shortcut for {@code getService(PackagingRegistry.class).require(...)}.
794 *
795 * @see org.apache.maven.api.services.PackagingRegistry#require(String)
796 */
797 @Nonnull
798 Packaging requirePackaging(@Nonnull String id);
799
800 /**
801 * Obtain the {@link ProjectScope} from the specified {@code id}.
802 * <p>
803 * Shortcut for {@code getService(ProjectScopeRegistry.class).require(...)}.
804 *
805 * @see org.apache.maven.api.services.ProjectScopeRegistry#require(String)
806 */
807 @Nonnull
808 ProjectScope requireProjectScope(@Nonnull String id);
809
810 /**
811 * Obtain the {@link DependencyScope} from the specified {@code id}.
812 * <p>
813 * Shortcut for {@code DependencyScope.forId(...)}.
814 *
815 * @see org.apache.maven.api.DependencyScope#forId(String)
816 */
817 @Nonnull
818 DependencyScope requireDependencyScope(@Nonnull String id);
819
820 /**
821 * Obtain the {@link PathScope} from the specified {@code id}.
822 * <p>
823 * Shortcut for {@code getService(PathScopeRegistry.class).require(...)}.
824 *
825 * @see org.apache.maven.api.services.PathScopeRegistry#require(String)
826 */
827 @Nonnull
828 PathScope requirePathScope(@Nonnull String id);
829 }