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 }