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 }