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 }