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