View Javadoc
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 }