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