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