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.internal.impl;
20  
21  import java.io.IOException;
22  import java.io.InputStream;
23  import java.io.UncheckedIOException;
24  import java.lang.module.ModuleDescriptor;
25  import java.nio.file.Files;
26  import java.nio.file.Path;
27  import java.util.Collection;
28  import java.util.Collections;
29  import java.util.HashMap;
30  import java.util.Map;
31  import java.util.jar.Attributes;
32  import java.util.jar.JarFile;
33  import java.util.jar.Manifest;
34  import java.util.stream.Stream;
35  import java.util.zip.ZipEntry;
36  
37  import org.apache.maven.api.JavaPathType;
38  import org.apache.maven.api.annotations.Nonnull;
39  
40  /**
41   * Information about the modules contained in a path element.
42   * The path element may be a JAR file or a directory. Directories may use either package hierarchy
43   * or module hierarchy, but not module source hierarchy. The latter is excluded because this class
44   * is for path elements of compiled codes.
45   */
46  class PathModularization {
47      /**
48       * A unique constant for all non-modular dependencies.
49       */
50      public static final PathModularization NONE = new PathModularization();
51  
52      /**
53       * Name of the file to use as a sentinel value for deciding if a directory or a JAR is modular.
54       */
55      private static final String MODULE_INFO = "module-info.class";
56  
57      /**
58       * The attribute for automatic module name in {@code META-INF/MANIFEST.MF} files.
59       */
60      private static final Attributes.Name AUTO_MODULE_NAME = new Attributes.Name("Automatic-Module-Name");
61  
62      /**
63       * Filename of the path specified at construction time.
64       */
65      private final String filename;
66  
67      /**
68       * Module information for the path specified at construction time.
69       * This map is usually either empty if no module was found, or a singleton map.
70       * It may however contain more than one entry if module hierarchy was detected,
71       * in which case there is one key per sub-directory.
72       *
73       * <p>Values are instances of either {@link ModuleDescriptor} or {@link String}.
74       * The latter case happens when a JAR file has no {@code module-info.class} entry
75       * but has an automatic name declared in {@code META-INF/MANIFEST.MF}.</p>
76       *
77       * <p>This map may contain null values if the constructor was invoked with {@code resolve}
78       * parameter set to false. This is more efficient when only the module existence needs to
79       * be tested, and module descriptors are not needed.</p>
80       */
81      @Nonnull
82      final Map<Path, Object> descriptors;
83  
84      /**
85       * Whether module hierarchy was detected. If false, then package hierarchy is assumed.
86       * In a package hierarchy, the {@linkplain #descriptors} map has either zero or one entry.
87       * In a module hierarchy, the descriptors map may have an arbitrary number of entries,
88       * including one (so the map size cannot be used as a criterion).
89       */
90      final boolean isModuleHierarchy;
91  
92      /**
93       * Constructs an empty instance for non-modular dependencies.
94       *
95       * @see #NONE
96       */
97      private PathModularization() {
98          filename = "(none)";
99          descriptors = Collections.emptyMap();
100         isModuleHierarchy = false;
101     }
102 
103     /**
104      * Finds module information in the given JAR file, output directory, or test output directory.
105      * If no module is found, or if module information cannot be extracted, then this constructor
106      * builds an empty map.
107      *
108      * <p>If the {@code resolve} parameter value is {@code false}, then some or all map values may
109      * be null instead of the actual module name. This option can avoid the cost of reading module
110      * descriptors when only the modules existence needs to be verified.</p>
111      *
112      * <p><b>Algorithm:</b>
113      * If the given path is a directory, then there is a choice:
114      * </p>
115      * <ul>
116      *   <li><b>Package hierarchy:</b> if a {@code module-info.class} file is found at the root,
117      *       then builds a singleton map with the module name declared in that descriptor.</li>
118      *   <li><b>Module hierarchy:</b> if {@code module-info.class} files are found in sub-directories,
119      *       at a deep intentionally restricted to one level, then builds a map of module names found
120      *       in the descriptor of each sub-directory.</li>
121      * </ul>
122      *
123      * Otherwise if the given path is a JAR file, then there is a choice:
124      * <ul>
125      *   <li>If a {@code module-info.class} file is found in the root directory or in a
126      *       {@code "META-INF/versions/{n}/"} subdirectory, builds a singleton map with
127      *       the module name declared in that descriptor.</li>
128      *   <li>Otherwise if an {@code "Automatic-Module-Name"} attribute is declared in the
129      *       {@code META-INF/MANIFEST.MF} file, builds a singleton map with the value of that attribute.</li>
130      * </ul>
131      *
132      * Otherwise builds an empty map.
133      *
134      * @param path directory or JAR file to test
135      * @param resolve whether the module names are requested. If false, null values may be used instead
136      * @throws IOException if an error occurred while reading the JAR file or the module descriptor
137      */
138     PathModularization(Path path, boolean resolve) throws IOException {
139         filename = path.getFileName().toString();
140         if (Files.isDirectory(path)) {
141             /*
142              * Package hierarchy: only one module with descriptor at the root.
143              * This is the layout of output directories in projects using the
144              * classical (Java 8 and before) way to organize source files.
145              */
146             Path file = path.resolve(MODULE_INFO);
147             if (Files.isRegularFile(file)) {
148                 ModuleDescriptor descriptor = null;
149                 if (resolve) {
150                     try (InputStream in = Files.newInputStream(file)) {
151                         descriptor = ModuleDescriptor.read(in);
152                     }
153                 }
154                 descriptors = Collections.singletonMap(file, descriptor);
155                 isModuleHierarchy = false;
156                 return;
157             }
158             /*
159              * Module hierarchy: many modules, one per directory, with descriptor at the root of the sub-directory.
160              * This is the layout of output directories in projects using the new (Java 9 and later) way to organize
161              * source files.
162              */
163             if (Files.isDirectory(file)) {
164                 var multi = new HashMap<Path, ModuleDescriptor>();
165                 try (Stream<Path> subdirs = Files.list(file)) {
166                     subdirs.filter(Files::isDirectory).forEach((subdir) -> {
167                         Path mf = subdir.resolve(MODULE_INFO);
168                         if (Files.isRegularFile(mf)) {
169                             ModuleDescriptor descriptor = null;
170                             if (resolve) {
171                                 try (InputStream in = Files.newInputStream(mf)) {
172                                     descriptor = ModuleDescriptor.read(in);
173                                 } catch (IOException e) {
174                                     throw new UncheckedIOException(e);
175                                 }
176                             }
177                             multi.put(mf, descriptor);
178                         }
179                     });
180                 } catch (UncheckedIOException e) {
181                     throw e.getCause();
182                 }
183                 if (!multi.isEmpty()) {
184                     descriptors = Collections.unmodifiableMap(multi);
185                     isModuleHierarchy = true;
186                     return;
187                 }
188             }
189         } else if (Files.isRegularFile(path)) {
190             /*
191              * JAR file: can contain only one module, with descriptor at the root.
192              * If no descriptor, the "Automatic-Module-Name" manifest attribute is
193              * taken as a fallback.
194              */
195             try (JarFile jar = new JarFile(path.toFile())) {
196                 ZipEntry entry = jar.getEntry(MODULE_INFO);
197                 if (entry != null) {
198                     ModuleDescriptor descriptor = null;
199                     if (resolve) {
200                         try (InputStream in = jar.getInputStream(entry)) {
201                             descriptor = ModuleDescriptor.read(in);
202                         }
203                     }
204                     descriptors = Collections.singletonMap(path, descriptor);
205                     isModuleHierarchy = false;
206                     return;
207                 }
208                 // No module descriptor, check manifest file.
209                 Manifest mf = jar.getManifest();
210                 if (mf != null) {
211                     Object name = mf.getMainAttributes().get(AUTO_MODULE_NAME);
212                     if (name instanceof String) {
213                         descriptors = Collections.singletonMap(path, name);
214                         isModuleHierarchy = false;
215                         return;
216                     }
217                 }
218             }
219         }
220         descriptors = Collections.emptyMap();
221         isModuleHierarchy = false;
222     }
223 
224     /**
225      * {@return the type of path detected}
226      * The return value is {@link JavaPathType#MODULES}
227      * if the dependency is a modular JAR file or a directory containing module descriptor(s),
228      * or {@link JavaPathType#CLASSES} otherwise. A JAR file without module descriptor but with
229      * an "Automatic-Module-Name" manifest attribute is considered modular.
230      */
231     public JavaPathType getPathType() {
232         return descriptors.isEmpty() ? JavaPathType.CLASSES : JavaPathType.MODULES;
233     }
234 
235     /**
236      * If the module has no name, adds the filename of the JAR file in the given collection.
237      * This method should be invoked for dependencies placed on {@link JavaPathType#MODULES}
238      * for preparing a warning asking to not deploy the build artifact on a public repository.
239      * If the module has an explicit name either with a {@code module-info.class} file or with
240      * an {@code "Automatic-Module-Name"} attribute in the {@code META-INF/MANIFEST.MF} file,
241      * then this method does nothing.
242      */
243     public void addIfFilenameBasedAutomodules(Collection<String> automodulesDetected) {
244         if (descriptors.isEmpty()) {
245             automodulesDetected.add(filename);
246         }
247     }
248 
249     /**
250      * {@return whether the dependency contains a module of the given name}
251      */
252     public boolean containsModule(String name) {
253         return descriptors.containsValue(name);
254     }
255 
256     /**
257      * {@return a string representation of this object for debugging purposes}
258      * This string representation may change in any future version.
259      */
260     @Override
261     public String toString() {
262         return getClass().getCanonicalName() + '[' + filename + ']';
263     }
264 }