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