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