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.services; 20 21 import java.io.IOException; 22 import java.lang.module.ModuleDescriptor; 23 import java.nio.file.Path; 24 import java.util.List; 25 import java.util.Map; 26 import java.util.Optional; 27 28 import org.apache.maven.api.Dependency; 29 import org.apache.maven.api.DependencyScope; 30 import org.apache.maven.api.JavaPathType; 31 import org.apache.maven.api.Node; 32 import org.apache.maven.api.PathType; 33 import org.apache.maven.api.annotations.Experimental; 34 import org.apache.maven.api.annotations.Nonnull; 35 import org.apache.maven.api.annotations.Nullable; 36 37 /** 38 * The result of a dependency resolution request. 39 * 40 * @since 4.0.0 41 * @see DependencyResolver#resolve(DependencyResolverRequest) 42 */ 43 @Experimental 44 public interface DependencyResolverResult { 45 46 /** 47 * Gets the exceptions that occurred while building the dependency graph. 48 * 49 * @return the exceptions that occurred, never {@code null} 50 */ 51 @Nonnull 52 List<Exception> getExceptions(); 53 54 /** 55 * Gets the root node of the dependency graph. 56 * 57 * @return the root node of the dependency graph or {@code null} if none 58 */ 59 @Nullable 60 Node getRoot(); 61 62 /** 63 * The ordered list of the flattened dependency nodes. 64 * 65 * @return the ordered list of the flattened dependency nodes 66 */ 67 @Nonnull 68 List<Node> getNodes(); 69 70 /** 71 * Returns the file paths of all dependencies, regardless on which tool option those paths should be placed. 72 * The returned list may contain a mix of Java class-path, Java module-path, and other types of path elements. 73 * This collection has the same content than {@code getDependencies.values()} except that it does not contain 74 * null elements. 75 * 76 * @return the paths of all dependencies 77 */ 78 @Nonnull 79 List<Path> getPaths(); 80 81 /** 82 * Returns the file paths of all dependencies, dispatched according the tool options where to place them. 83 * The {@link PathType} keys identify, for example, {@code --class-path} or {@code --module-path} options. 84 * In the case of Java tools, the map may also contain {@code --patch-module} options, which are 85 * {@linkplain org.apache.maven.api.JavaPathType#patchModule(String) handled in a special way}. 86 * 87 * <h4>Design note</h4> 88 * All types of path are determined together because they are sometime mutually exclusive. 89 * For example, an artifact of type {@value org.apache.maven.api.Type#JAR} can be placed 90 * either on the class-path or on the module-path. The project needs to make a choice 91 * (possibly using heuristic rules), then to add the dependency in only one of the options 92 * identified by {@link PathType}. 93 * 94 * @return file paths to place on the different tool options 95 */ 96 @Nonnull 97 Map<PathType, List<Path>> getDispatchedPaths(); 98 99 /** 100 * {@return all dependencies associated to their paths} 101 * Some dependencies may be associated to a null value if there is no path available. 102 */ 103 @Nonnull 104 Map<Dependency, Path> getDependencies(); 105 106 /** 107 * Returns the Java module name of the dependency at the given path. 108 * The given dependency should be one of the paths returned by {@link #getDependencies()}. 109 * The module name is extracted from the {@code module-info.class} file if present, otherwise from 110 * the {@code "Automatic-Module-Name"} attribute of the {@code META-INF/MANIFEST.MF} file if present. 111 * 112 * <p>A typical usage is to invoke this method for all dependencies having a 113 * {@link DependencyScope#TEST TEST} or {@link DependencyScope#TEST_ONLY TEST_ONLY} 114 * {@linkplain Dependency#getScope() scope}. An {@code --add-reads} option may need 115 * to be generated for compiling and running the test classes that use such dependencies.</p> 116 * 117 * @param dependency path to the dependency for which to get the module name 118 * @return module name of the dependency at the given path, or empty if the dependency is not modular 119 * @throws IOException if the module information of the specified dependency cannot be read 120 */ 121 Optional<String> getModuleName(@Nonnull Path dependency) throws IOException; 122 123 /** 124 * Returns the Java module descriptor of the dependency at the given path. 125 * The given dependency should be one of the paths returned by {@link #getDependencies()}. 126 * The module descriptor is extracted from the {@code module-info.class} file if present. 127 * 128 * <p>{@link #getModuleName(Path)} is preferred when only the module name is desired, 129 * because a name may be present even if the descriptor is absent. This method is for 130 * cases when more information is desired, such as the set of exported packages.</p> 131 * 132 * @param dependency path to the dependency for which to get the module name 133 * @return module name of the dependency at the given path, or empty if the dependency is not modular 134 * @throws IOException if the module information of the specified dependency cannot be read 135 */ 136 Optional<ModuleDescriptor> getModuleDescriptor(@Nonnull Path dependency) throws IOException; 137 138 /** 139 * If the module-path contains at least one filename-based auto-module, prepares a warning message. 140 * The module path is the collection of dependencies associated to {@link JavaPathType#MODULES}. 141 * It is caller's responsibility to send the message to a logger. 142 * 143 * @return warning message if at least one filename-based auto-module was found 144 */ 145 Optional<String> warningForFilenameBasedAutomodules(); 146 }