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.plugins.javadoc;
20  
21  import java.io.BufferedReader;
22  import java.io.File;
23  import java.io.FileNotFoundException;
24  import java.io.FileOutputStream;
25  import java.io.IOException;
26  import java.io.InputStreamReader;
27  import java.io.OutputStream;
28  import java.io.PrintStream;
29  import java.io.UnsupportedEncodingException;
30  import java.lang.reflect.Modifier;
31  import java.net.SocketTimeoutException;
32  import java.net.URI;
33  import java.net.URISyntaxException;
34  import java.net.URL;
35  import java.net.URLClassLoader;
36  import java.nio.charset.Charset;
37  import java.nio.charset.IllegalCharsetNameException;
38  import java.nio.file.FileVisitResult;
39  import java.nio.file.Files;
40  import java.nio.file.Path;
41  import java.nio.file.Paths;
42  import java.nio.file.SimpleFileVisitor;
43  import java.nio.file.attribute.BasicFileAttributes;
44  import java.util.ArrayList;
45  import java.util.Arrays;
46  import java.util.Collection;
47  import java.util.Collections;
48  import java.util.LinkedHashSet;
49  import java.util.List;
50  import java.util.NoSuchElementException;
51  import java.util.Properties;
52  import java.util.Set;
53  import java.util.StringTokenizer;
54  import java.util.jar.JarEntry;
55  import java.util.jar.JarInputStream;
56  import java.util.regex.Matcher;
57  import java.util.regex.Pattern;
58  import java.util.regex.PatternSyntaxException;
59  import java.util.stream.Collectors;
60  
61  import org.apache.http.HttpHeaders;
62  import org.apache.http.HttpHost;
63  import org.apache.http.HttpResponse;
64  import org.apache.http.HttpStatus;
65  import org.apache.http.auth.AuthScope;
66  import org.apache.http.auth.Credentials;
67  import org.apache.http.auth.UsernamePasswordCredentials;
68  import org.apache.http.client.CredentialsProvider;
69  import org.apache.http.client.config.CookieSpecs;
70  import org.apache.http.client.config.RequestConfig;
71  import org.apache.http.client.methods.HttpGet;
72  import org.apache.http.client.protocol.HttpClientContext;
73  import org.apache.http.config.Registry;
74  import org.apache.http.config.RegistryBuilder;
75  import org.apache.http.conn.socket.ConnectionSocketFactory;
76  import org.apache.http.conn.socket.PlainConnectionSocketFactory;
77  import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
78  import org.apache.http.impl.client.BasicCredentialsProvider;
79  import org.apache.http.impl.client.CloseableHttpClient;
80  import org.apache.http.impl.client.HttpClientBuilder;
81  import org.apache.http.impl.client.HttpClients;
82  import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
83  import org.apache.http.message.BasicHeader;
84  import org.apache.maven.plugin.logging.Log;
85  import org.apache.maven.project.MavenProject;
86  import org.apache.maven.settings.Proxy;
87  import org.apache.maven.settings.Settings;
88  import org.apache.maven.shared.invoker.DefaultInvocationRequest;
89  import org.apache.maven.shared.invoker.DefaultInvoker;
90  import org.apache.maven.shared.invoker.InvocationOutputHandler;
91  import org.apache.maven.shared.invoker.InvocationRequest;
92  import org.apache.maven.shared.invoker.InvocationResult;
93  import org.apache.maven.shared.invoker.Invoker;
94  import org.apache.maven.shared.invoker.MavenInvocationException;
95  import org.apache.maven.shared.invoker.PrintStreamHandler;
96  import org.apache.maven.shared.utils.io.DirectoryScanner;
97  import org.apache.maven.shared.utils.io.FileUtils;
98  import org.apache.maven.wagon.proxy.ProxyInfo;
99  import org.apache.maven.wagon.proxy.ProxyUtils;
100 import org.codehaus.plexus.languages.java.version.JavaVersion;
101 import org.codehaus.plexus.util.cli.CommandLineException;
102 import org.codehaus.plexus.util.cli.CommandLineUtils;
103 import org.codehaus.plexus.util.cli.Commandline;
104 
105 /**
106  * Set of utilities methods for Javadoc.
107  *
108  * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
109  * @since 2.4
110  */
111 public class JavadocUtil {
112     /** The default timeout used when fetching url, i.e. 2000. */
113     public static final int DEFAULT_TIMEOUT = 2000;
114 
115     /** Error message when VM could not be started using invoker. */
116     protected static final String ERROR_INIT_VM =
117             "Error occurred during initialization of VM, try to reduce the Java heap size for the MAVEN_OPTS "
118                     + "environment variable using -Xms:<size> and -Xmx:<size>.";
119 
120     /**
121      * Method that removes invalid classpath elements in the specified paths.
122      * <b>Note</b>: All elements in {@code paths} could be absolute or relative against the project's base directory.
123      * When pruning classpath elements, you can optionally include files in the result, otherwise only directories are
124      * permitted.
125      *
126      * @param project the current Maven project not null
127      * @param paths the collection of paths that will be validated
128      * @param includeFiles whether to include files in the result as well
129      * @return a list of valid classpath elements as absolute paths
130      */
131     public static Collection<Path> prunePaths(MavenProject project, Collection<String> paths, boolean includeFiles) {
132         final Path projectBasedir = project.getBasedir().toPath();
133 
134         Set<Path> pruned = new LinkedHashSet<>(paths.size());
135         for (String path : paths) {
136             if (path == null) {
137                 continue;
138             }
139 
140             Path resolvedPath = projectBasedir.resolve(path);
141 
142             if (Files.isDirectory(resolvedPath) || includeFiles && Files.isRegularFile(resolvedPath)) {
143                 pruned.add(resolvedPath.toAbsolutePath());
144             }
145         }
146 
147         return pruned;
148     }
149 
150     /**
151      * Method that removes the invalid classpath directories in the specified directories.
152      * <b>Note</b>: All elements in {@code dirs} could be absolute or relative against the project's base directory.
153      *
154      * @param project the current Maven project not null
155      * @param dirs the collection of directories that will be validated
156      * @return a list of valid claspath elements as absolute paths
157      */
158     public static Collection<Path> pruneDirs(MavenProject project, Collection<String> dirs) {
159         return prunePaths(project, dirs, false);
160     }
161 
162     /**
163      * Method that removes the invalid files in the specified files. <b>Note</b>: All elements in <code>files</code>
164      * should be an absolute <code>String</code> path.
165      *
166      * @param files the list of <code>String</code> files paths that will be validated.
167      * @return a List of valid <code>File</code> objects.
168      */
169     protected static List<String> pruneFiles(Collection<String> files) {
170         List<String> pruned = new ArrayList<>(files.size());
171         for (String f : files) {
172             if (!shouldPruneFile(f, pruned)) {
173                 pruned.add(f);
174             }
175         }
176 
177         return pruned;
178     }
179 
180     /**
181      * Determine whether a file should be excluded from the provided list of paths, based on whether it exists and is
182      * already present in the list.
183      *
184      * @param f The files.
185      * @param pruned The list of pruned files..
186      * @return true if the file could be pruned false otherwise.
187      */
188     public static boolean shouldPruneFile(String f, List<String> pruned) {
189         if (f != null) {
190             if (Files.isRegularFile(Paths.get(f)) && !pruned.contains(f)) {
191                 return false;
192             }
193         }
194 
195         return true;
196     }
197 
198     /**
199      * Method that gets all the source files to be excluded from the javadoc on the given source paths.
200      *
201      * @param sourcePaths the path to the source files
202      * @param excludedPackages the package names to be excluded in the javadoc
203      * @return a List of the packages to be excluded in the generated javadoc
204      */
205     protected static List<String> getExcludedPackages(
206             Collection<Path> sourcePaths, Collection<String> excludedPackages) {
207         List<String> excludedNames = new ArrayList<>();
208         for (Path sourcePath : sourcePaths) {
209             excludedNames.addAll(getExcludedPackages(sourcePath, excludedPackages));
210         }
211 
212         return excludedNames;
213     }
214 
215     /**
216      * Convenience method to wrap a command line option-argument in single quotes (i.e. <code>'</code>). Intended for values which
217      * may contain whitespace. <br>
218      * Line feeds (i.e. <code>\n</code>) are replaced with spaces, and single quotes are backslash escaped.
219      *
220      * @param value the option-argument
221      * @return quoted option-argument
222      */
223     protected static String quotedArgument(String value) {
224         if (value == null) {
225             return null;
226         }
227         String arg = value;
228 
229         List<String> list = Arrays.stream(arg.split("\n")).map(String::trim).collect(Collectors.toList());
230         arg = String.join("", list);
231 
232         if (arg != null && !arg.isEmpty()) {
233             arg = arg.replace("'", "\\'");
234             arg = "'" + arg + "'";
235         }
236 
237         return arg;
238     }
239 
240     /**
241      * Convenience method to format a path argument so that it is properly interpreted by the javadoc tool. Intended for
242      * path values which may contain whitespaces.
243      *
244      * @param value the argument value.
245      * @return path argument with quote
246      */
247     protected static String quotedPathArgument(String value) {
248         String path = value;
249 
250         if (path != null && !path.isEmpty()) {
251             path = path.replace('\\', '/');
252             if (path.contains("'")) {
253                 StringBuilder pathBuilder = new StringBuilder();
254                 pathBuilder.append('\'');
255                 String[] split = path.split("'");
256 
257                 for (int i = 0; i < split.length; i++) {
258                     if (i != split.length - 1) {
259                         pathBuilder.append(split[i].trim()).append("\\'");
260                     } else {
261                         pathBuilder.append(split[i]);
262                     }
263                 }
264                 pathBuilder.append('\'');
265                 path = pathBuilder.toString();
266             } else {
267                 path = "'" + path + "'";
268             }
269         }
270 
271         return path;
272     }
273 
274     /**
275      * Convenience method that copy all <code>doc-files</code> directories from <code>javadocDir</code> to the
276      * <code>outputDirectory</code>.
277      *
278      * @param outputDirectory the output directory
279      * @param javadocDir the javadoc directory
280      * @param excludedocfilessubdir the excludedocfilessubdir parameter
281      * @throws IOException if any
282      * @since 2.5
283      */
284     protected static void copyJavadocResources(File outputDirectory, File javadocDir, String excludedocfilessubdir)
285             throws IOException {
286         if (!javadocDir.isDirectory()) {
287             return;
288         }
289 
290         List<String> excludes = new ArrayList<>(Arrays.asList(FileUtils.getDefaultExcludes()));
291 
292         if (excludedocfilessubdir != null && !excludedocfilessubdir.isEmpty()) {
293             StringTokenizer st = new StringTokenizer(excludedocfilessubdir, ":");
294             String current;
295             while (st.hasMoreTokens()) {
296                 current = st.nextToken();
297                 excludes.add("**/" + current.trim() + "/**");
298             }
299         }
300 
301         List<String> docFiles = FileUtils.getDirectoryNames(
302                 javadocDir, "resources,**/doc-files", String.join(",", excludes), false, true);
303         for (String docFile : docFiles) {
304             File docFileOutput = new File(outputDirectory, docFile);
305             FileUtils.mkdir(docFileOutput.getAbsolutePath());
306             FileUtils.copyDirectoryStructure(new File(javadocDir, docFile), docFileOutput);
307             List<String> files = FileUtils.getFileAndDirectoryNames(
308                     docFileOutput, String.join(",", excludes), null, true, true, true, true);
309             for (String filename : files) {
310                 File file = new File(filename);
311 
312                 if (file.isDirectory()) {
313                     FileUtils.deleteDirectory(file);
314                 } else {
315                     file.delete();
316                 }
317             }
318         }
319     }
320 
321     /**
322      * Method that gets the files or classes that would be included in the javadocs using the subpackages parameter.
323      *
324      * @param sourceDirectory the directory where the source files are located
325      * @param fileList the list of all relative files found in the sourceDirectory
326      * @param excludePackages package names to be excluded in the javadoc
327      * @return a StringBuilder that contains the appended file names of the files to be included in the javadoc
328      */
329     protected static List<String> getIncludedFiles(
330             File sourceDirectory, String[] fileList, Collection<String> excludePackages) {
331         List<String> files = new ArrayList<>();
332 
333         List<Pattern> excludePackagePatterns = new ArrayList<>(excludePackages.size());
334         for (String excludePackage : excludePackages) {
335             excludePackagePatterns.add(Pattern.compile(excludePackage
336                     .replace('.', File.separatorChar)
337                     .replace("\\", "\\\\")
338                     .replace("*", ".+")
339                     .concat("[\\\\/][^\\\\/]+\\.java")));
340         }
341 
342         for (String file : fileList) {
343             boolean excluded = false;
344             for (Pattern excludePackagePattern : excludePackagePatterns) {
345                 if (excludePackagePattern.matcher(file).matches()) {
346                     excluded = true;
347                     break;
348                 }
349             }
350 
351             if (!excluded) {
352                 files.add(file.replace('\\', '/'));
353             }
354         }
355 
356         return files;
357     }
358 
359     /**
360      * Method that gets the complete package names (including subpackages) of the packages that were defined in the
361      * excludePackageNames parameter.
362      *
363      * @param sourceDirectory the directory where the source files are located
364      * @param excludePackagenames package names to be excluded in the javadoc
365      * @return a List of the packagenames to be excluded
366      */
367     protected static Collection<String> getExcludedPackages(
368             final Path sourceDirectory, Collection<String> excludePackagenames) {
369         final String regexFileSeparator = File.separator.replace("\\", "\\\\");
370 
371         final Collection<String> fileList = new ArrayList<>();
372 
373         try {
374             Files.walkFileTree(sourceDirectory, new SimpleFileVisitor<Path>() {
375                 @Override
376                 public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
377                     if (file.getFileName().toString().endsWith(".java")) {
378                         fileList.add(
379                                 sourceDirectory.relativize(file.getParent()).toString());
380                     }
381                     return FileVisitResult.CONTINUE;
382                 }
383             });
384         } catch (IOException e) {
385             // noop
386         }
387 
388         List<String> files = new ArrayList<>();
389         for (String excludePackagename : excludePackagenames) {
390             // Usage of wildcard was bad specified and bad implemented, i.e. using String.contains()
391             //   without respecting surrounding context
392             // Following implementation should match requirements as defined in the examples:
393             // - A wildcard at the beginning should match one or more directories
394             // - Any other wildcard must match exactly one directory
395             Pattern p = Pattern.compile(excludePackagename
396                     .replace(".", regexFileSeparator)
397                     .replaceFirst("^\\*", ".+")
398                     .replace("*", "[^" + regexFileSeparator + "]+"));
399 
400             for (String aFileList : fileList) {
401                 if (p.matcher(aFileList).matches()) {
402                     files.add(aFileList.replace(File.separatorChar, '.'));
403                 }
404             }
405         }
406 
407         return files;
408     }
409 
410     /**
411      * Convenience method that gets the files to be included in the javadoc.
412      *
413      * @param sourceDirectory the directory where the source files are located
414      * @param sourceFileIncludes files to include
415      * @param sourceFileExcludes files to exclude
416      * @param excludePackages packages to be excluded from the javadocs
417      * @return the files from which javadoc should be generated
418      */
419     protected static List<String> getFilesFromSource(
420             File sourceDirectory,
421             List<String> sourceFileIncludes,
422             List<String> sourceFileExcludes,
423             Collection<String> excludePackages) {
424         DirectoryScanner ds = new DirectoryScanner();
425         if (sourceFileIncludes == null) {
426             sourceFileIncludes = Collections.singletonList("**/*.java");
427         }
428         ds.setIncludes(sourceFileIncludes.toArray(new String[0]));
429         if (sourceFileExcludes != null && !sourceFileExcludes.isEmpty()) {
430             ds.setExcludes(sourceFileExcludes.toArray(new String[0]));
431         }
432         ds.setBasedir(sourceDirectory);
433         ds.scan();
434 
435         String[] fileList = ds.getIncludedFiles();
436 
437         List<String> files = new ArrayList<>();
438         if (fileList.length != 0) {
439             files.addAll(getIncludedFiles(sourceDirectory, fileList, excludePackages));
440         }
441 
442         return files;
443     }
444 
445     /**
446      * Call the Javadoc tool and parse its output to find its version, i.e.:
447      *
448      * <pre>
449      * javadoc.exe( or.sh ) - J - version
450      * </pre>
451      *
452      * @param javadocExe not null file
453      * @return the javadoc version as float
454      * @throws IOException if javadocExe is null, doesn't exist or is not a file
455      * @throws CommandLineException if any
456      * @throws IllegalArgumentException if no output was found in the command line
457      * @throws PatternSyntaxException if the output contains a syntax error in the regular-expression pattern.
458      * @see #extractJavadocVersion(String)
459      */
460     protected static JavaVersion getJavadocVersion(File javadocExe)
461             throws IOException, CommandLineException, IllegalArgumentException {
462         if ((javadocExe == null) || (!javadocExe.exists()) || (!javadocExe.isFile())) {
463             throw new IOException("The javadoc executable '" + javadocExe + "' doesn't exist or is not a file. ");
464         }
465 
466         Commandline cmd = new Commandline();
467         cmd.setExecutable(javadocExe.getAbsolutePath());
468         cmd.setWorkingDirectory(javadocExe.getParentFile());
469         cmd.createArg().setValue("-J-version");
470 
471         CommandLineUtils.StringStreamConsumer out = new JavadocOutputStreamConsumer();
472         CommandLineUtils.StringStreamConsumer err = new JavadocOutputStreamConsumer();
473 
474         int exitCode = CommandLineUtils.executeCommandLine(cmd, out, err);
475         String errOutput = err.getOutput(); // non-null
476         if (exitCode != 0) {
477             StringBuilder msg = new StringBuilder("Exit code: " + exitCode + " - " + errOutput);
478             msg.append('\n');
479             msg.append("Command line was:").append(CommandLineUtils.toString(cmd.getCommandline()));
480             throw new CommandLineException(msg.toString());
481         }
482 
483         if (!errOutput.isEmpty()) {
484             return JavaVersion.parse(extractJavadocVersion(errOutput));
485         } else {
486             String outOutput = out.getOutput(); // non-null
487             if (!outOutput.isEmpty()) {
488                 return JavaVersion.parse(extractJavadocVersion(outOutput));
489             }
490         }
491 
492         throw new IllegalArgumentException("No output found from the command line 'javadoc -J-version'");
493     }
494 
495     private static final Pattern EXTRACT_JAVADOC_VERSION_PATTERN =
496             Pattern.compile("(?s).*?[^a-zA-Z](([0-9]+\\.?[0-9]*)(\\.[0-9]+)?).*");
497 
498     /**
499      * Parse the output for 'javadoc -J-version' and return the javadoc version recognized. <br>
500      * Here are some output for 'javadoc -J-version' depending the JDK used:
501      * <table><caption>Output for 'javadoc -J-version' per JDK</caption>
502      * <tr>
503      * <th>JDK</th>
504      * <th>Output for 'javadoc -J-version'</th>
505      * </tr>
506      * <tr>
507      * <td>Sun 1.4</td>
508      * <td>java full version "1.4.2_12-b03"</td>
509      * </tr>
510      * <tr>
511      * <td>Sun 1.5</td>
512      * <td>java full version "1.5.0_07-164"</td>
513      * </tr>
514      * <tr>
515      * <td>IBM 1.4</td>
516      * <td>javadoc full version "J2RE 1.4.2 IBM Windows 32 build cn1420-20040626"</td>
517      * </tr>
518      * <tr>
519      * <td>IBM 1.5 (French JVM)</td>
520      * <td>javadoc version complète de "J2RE 1.5.0 IBM Windows 32 build pwi32pdev-20070426a"</td>
521      * </tr>
522      * <tr>
523      * <td>FreeBSD 1.5</td>
524      * <td>java full version "diablo-1.5.0-b01"</td>
525      * </tr>
526      * <tr>
527      * <td>BEA jrockit 1.5</td>
528      * <td>java full version "1.5.0_11-b03"</td>
529      * </tr>
530      * </table>
531      *
532      * @param output for 'javadoc -J-version'
533      * @return the version of the javadoc for the output, only digits and dots
534      * @throws PatternSyntaxException if the output doesn't match with the output pattern
535      *             {@code (?s).*?[^a-zA-Z]([0-9]+\\.?[0-9]*)(\\.([0-9]+))?.*}.
536      * @throws IllegalArgumentException if the output is null
537      */
538     protected static String extractJavadocVersion(String output) throws IllegalArgumentException {
539         if (output == null || output.isEmpty()) {
540             throw new IllegalArgumentException("The output could not be null.");
541         }
542 
543         Pattern pattern = EXTRACT_JAVADOC_VERSION_PATTERN;
544 
545         Matcher matcher = pattern.matcher(output);
546         if (!matcher.matches()) {
547             throw new PatternSyntaxException(
548                     "Unrecognized version of Javadoc: '" + output + "'",
549                     pattern.pattern(),
550                     pattern.toString().length() - 1);
551         }
552 
553         return matcher.group(1);
554     }
555 
556     private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_0 = Pattern.compile("^\\s*(\\d+)\\s*?\\s*$");
557 
558     private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_1 =
559             Pattern.compile("^\\s*(\\d+)\\s*k(b)?\\s*$", Pattern.CASE_INSENSITIVE);
560 
561     private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_2 =
562             Pattern.compile("^\\s*(\\d+)\\s*m(b)?\\s*$", Pattern.CASE_INSENSITIVE);
563 
564     private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_3 =
565             Pattern.compile("^\\s*(\\d+)\\s*g(b)?\\s*$", Pattern.CASE_INSENSITIVE);
566 
567     private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_4 =
568             Pattern.compile("^\\s*(\\d+)\\s*t(b)?\\s*$", Pattern.CASE_INSENSITIVE);
569 
570     /**
571      * Parse a memory string which be used in the JVM arguments <code>-Xms</code> or <code>-Xmx</code>. <br>
572      * Here are some supported memory string depending the JDK used:
573      * <table><caption>Memory argument support per JDK</caption>
574      * <tr>
575      * <th>JDK</th>
576      * <th>Memory argument support for <code>-Xms</code> or <code>-Xmx</code></th>
577      * </tr>
578      * <tr>
579      * <td>SUN</td>
580      * <td>1024k | 128m | 1g | 1t</td>
581      * </tr>
582      * <tr>
583      * <td>IBM</td>
584      * <td>1024k | 1024b | 128m | 128mb | 1g | 1gb</td>
585      * </tr>
586      * <tr>
587      * <td>BEA</td>
588      * <td>1024k | 1024kb | 128m | 128mb | 1g | 1gb</td>
589      * </tr>
590      * </table>
591      *
592      * @param memory the memory to be parsed, not null.
593      * @return the memory parsed with a supported unit. If no unit specified in the <code>memory</code> parameter, the
594      *         default unit is <code>m</code>. The units <code>g | gb</code> or <code>t | tb</code> will be converted in
595      *         <code>m</code>.
596      * @throws IllegalArgumentException if the <code>memory</code> parameter is null or doesn't match any pattern.
597      */
598     protected static String parseJavadocMemory(String memory) throws IllegalArgumentException {
599         if (memory == null || memory.isEmpty()) {
600             throw new IllegalArgumentException("The memory could not be null.");
601         }
602 
603         Matcher m0 = PARSE_JAVADOC_MEMORY_PATTERN_0.matcher(memory);
604         if (m0.matches()) {
605             return m0.group(1) + "m";
606         }
607 
608         Matcher m1 = PARSE_JAVADOC_MEMORY_PATTERN_1.matcher(memory);
609         if (m1.matches()) {
610             return m1.group(1) + "k";
611         }
612 
613         Matcher m2 = PARSE_JAVADOC_MEMORY_PATTERN_2.matcher(memory);
614         if (m2.matches()) {
615             return m2.group(1) + "m";
616         }
617 
618         Matcher m3 = PARSE_JAVADOC_MEMORY_PATTERN_3.matcher(memory);
619         if (m3.matches()) {
620             return (Integer.parseInt(m3.group(1)) * 1024) + "m";
621         }
622 
623         Matcher m4 = PARSE_JAVADOC_MEMORY_PATTERN_4.matcher(memory);
624         if (m4.matches()) {
625             return (Integer.parseInt(m4.group(1)) * 1024 * 1024) + "m";
626         }
627 
628         throw new IllegalArgumentException("Could convert not to a memory size: " + memory);
629     }
630 
631     /**
632      * Validate if a charset is supported on this platform.
633      *
634      * @param charsetName the charsetName to be check.
635      * @return <code>true</code> if the given charset is supported by the JVM, <code>false</code> otherwise.
636      */
637     protected static boolean validateEncoding(String charsetName) {
638         if (charsetName == null || charsetName.isEmpty()) {
639             return false;
640         }
641 
642         try {
643             return Charset.isSupported(charsetName);
644         } catch (IllegalCharsetNameException e) {
645             return false;
646         }
647     }
648 
649     /**
650      * Auto-detect the class names of the implementation of <code>com.sun.tools.doclets.Taglet</code> class from a given
651      * jar file. <br>
652      * <b>Note</b>: <code>JAVA_HOME/lib/tools.jar</code> is a requirement to find
653      * <code>com.sun.tools.doclets.Taglet</code> class.
654      *
655      * @param jarFile not null
656      * @return the list of <code>com.sun.tools.doclets.Taglet</code> class names from a given jarFile.
657      * @throws IOException if jarFile is invalid or not found, or if the <code>JAVA_HOME/lib/tools.jar</code> is not
658      *             found.
659      * @throws ClassNotFoundException if any
660      * @throws NoClassDefFoundError if any
661      */
662     protected static List<String> getTagletClassNames(File jarFile)
663             throws IOException, ClassNotFoundException, NoClassDefFoundError {
664         List<String> classes = getClassNamesFromJar(jarFile);
665         URLClassLoader cl;
666 
667         // Needed to find com.sun.tools.doclets.Taglet class
668         File tools = new File(System.getProperty("java.home"), "../lib/tools.jar");
669         if (tools.exists() && tools.isFile()) {
670             cl = new URLClassLoader(
671                     new URL[] {jarFile.toURI().toURL(), tools.toURI().toURL()}, null);
672         } else {
673             cl = new URLClassLoader(new URL[] {jarFile.toURI().toURL()}, ClassLoader.getSystemClassLoader());
674         }
675 
676         List<String> tagletClasses = new ArrayList<>();
677 
678         Class<?> tagletClass;
679 
680         try {
681             tagletClass = cl.loadClass("com.sun.tools.doclets.Taglet");
682         } catch (ClassNotFoundException e) {
683             tagletClass = cl.loadClass("jdk.javadoc.doclet.Taglet");
684         }
685 
686         for (String s : classes) {
687             Class<?> c = cl.loadClass(s);
688 
689             if (tagletClass.isAssignableFrom(c) && !Modifier.isAbstract(c.getModifiers())) {
690                 tagletClasses.add(c.getName());
691             }
692         }
693 
694         try {
695             cl.close();
696         } catch (IOException ex) {
697             // no big deal
698         }
699 
700         return tagletClasses;
701     }
702 
703     /**
704      * Copy the given url to the given file.
705      *
706      * @param url not null url
707      * @param file not null file where the url will be created
708      * @throws IOException if any
709      * @since 2.6
710      */
711     protected static void copyResource(URL url, File file) throws IOException {
712         if (file == null) {
713             throw new NullPointerException("The file can't be null.");
714         }
715         if (url == null) {
716             throw new NullPointerException("The url could not be null.");
717         }
718 
719         FileUtils.copyURLToFile(url, file);
720     }
721 
722     /**
723      * Invoke Maven for the given project file with a list of goals and properties, the output will be in the invokerlog
724      * file. <br>
725      * <b>Note</b>: the Maven Home should be defined in the <code>maven.home</code> Java system property or defined in
726      * <code>M2_HOME</code> system env variables.
727      *
728      * @param log a logger could be null.
729      * @param localRepositoryDir the localRepository not null.
730      * @param projectFile a not null project file.
731      * @param goals a not null goals list.
732      * @param properties the properties for the goals, could be null.
733      * @param invokerLog the log file where the invoker will be written, if null using <code>System.out</code>.
734      * @param globalSettingsFile reference to settings file, could be null.
735      * @param userSettingsFile reference to user settings file, could be null.
736      * @param globalToolchainsFile reference to toolchains file, could be null.
737      * @param userToolchainsFile reference to user toolchains file, could be null.
738      * @throws MavenInvocationException if any
739      * @since 2.6
740      */
741     protected static void invokeMaven(
742             Log log,
743             File localRepositoryDir,
744             File projectFile,
745             List<String> goals,
746             Properties properties,
747             File invokerLog,
748             File globalSettingsFile,
749             File userSettingsFile,
750             File globalToolchainsFile,
751             File userToolchainsFile)
752             throws MavenInvocationException {
753         if (projectFile == null) {
754             throw new IllegalArgumentException("projectFile should be not null.");
755         }
756         if (!projectFile.isFile()) {
757             throw new IllegalArgumentException(projectFile.getAbsolutePath() + " is not a file.");
758         }
759         if (goals == null || goals.isEmpty()) {
760             throw new IllegalArgumentException("goals should be not empty.");
761         }
762         if (localRepositoryDir == null || !localRepositoryDir.isDirectory()) {
763             throw new IllegalArgumentException(
764                     "localRepositoryDir '" + localRepositoryDir + "' should be a directory.");
765         }
766 
767         String mavenHome = getMavenHome(log);
768         if (mavenHome == null || mavenHome.isEmpty()) {
769             String msg = "Could NOT invoke Maven because no Maven Home is defined. You need to have set the M2_HOME "
770                     + "system env variable or a maven.home Java system properties.";
771             if (log != null) {
772                 log.error(msg);
773             } else {
774                 System.err.println(msg);
775             }
776             return;
777         }
778 
779         Invoker invoker = new DefaultInvoker();
780         invoker.setMavenHome(new File(mavenHome));
781         invoker.setLocalRepositoryDirectory(localRepositoryDir);
782 
783         InvocationRequest request = new DefaultInvocationRequest();
784         request.setBaseDirectory(projectFile.getParentFile());
785         request.setPomFile(projectFile);
786         if (globalSettingsFile != null && globalSettingsFile.isFile()) {
787             request.setGlobalSettingsFile(globalSettingsFile);
788         }
789         if (userSettingsFile != null && userSettingsFile.isFile()) {
790             request.setUserSettingsFile(userSettingsFile);
791         }
792         if (globalToolchainsFile != null && globalToolchainsFile.isFile()) {
793             request.setGlobalToolchainsFile(globalToolchainsFile);
794         }
795         if (userToolchainsFile != null && userToolchainsFile.isFile()) {
796             request.setToolchainsFile(userToolchainsFile);
797         }
798         request.setBatchMode(true);
799         if (log != null) {
800             request.setDebug(log.isDebugEnabled());
801         } else {
802             request.setDebug(true);
803         }
804         request.setGoals(goals);
805         if (properties != null) {
806             request.setProperties(properties);
807         }
808         File javaHome = getJavaHome(log);
809         if (javaHome != null) {
810             request.setJavaHome(javaHome);
811         }
812 
813         if (log != null && log.isDebugEnabled()) {
814             log.debug("Invoking Maven for the goals: " + goals + " with "
815                     + (properties == null ? "no properties" : "properties=" + properties));
816         }
817         InvocationResult result = invoke(log, invoker, request, invokerLog, goals, properties, null);
818 
819         if (result.getExitCode() != 0) {
820             String invokerLogContent = readFile(invokerLog, "UTF-8");
821 
822             // see DefaultMaven
823             if (invokerLogContent != null
824                     && (!invokerLogContent.contains("Scanning for projects...")
825                             || invokerLogContent.contains(OutOfMemoryError.class.getName()))) {
826                 if (log != null) {
827                     log.error("Error occurred during initialization of VM, trying to use an empty MAVEN_OPTS...");
828 
829                     if (log.isDebugEnabled()) {
830                         log.debug("Reinvoking Maven for the goals: " + goals + " with an empty MAVEN_OPTS...");
831                     }
832                 }
833                 result = invoke(log, invoker, request, invokerLog, goals, properties, "");
834             }
835         }
836 
837         if (result.getExitCode() != 0) {
838             String invokerLogContent = readFile(invokerLog, "UTF-8");
839 
840             // see DefaultMaven
841             if (invokerLogContent != null
842                     && (!invokerLogContent.contains("Scanning for projects...")
843                             || invokerLogContent.contains(OutOfMemoryError.class.getName()))) {
844                 throw new MavenInvocationException(ERROR_INIT_VM);
845             }
846 
847             throw new MavenInvocationException(
848                     "Error when invoking Maven, consult the invoker log file: " + invokerLog.getAbsolutePath());
849         }
850     }
851 
852     /**
853      * Read the given file and return the content or null if an IOException occurs.
854      *
855      * @param javaFile not null
856      * @param encoding could be null
857      * @return the content with unified line separator of the given javaFile using the given encoding.
858      * @see FileUtils#fileRead(File, String)
859      * @since 2.6.1
860      */
861     protected static String readFile(final File javaFile, final String encoding) {
862         try {
863             return FileUtils.fileRead(javaFile, encoding);
864         } catch (IOException e) {
865             return null;
866         }
867     }
868 
869     /**
870      * Split the given path with colon and semi-colon, to support Solaris and Windows path. Examples:
871      *
872      * <pre>
873      * splitPath( "/home:/tmp" )     = ["/home", "/tmp"]
874      * splitPath( "/home;/tmp" )     = ["/home", "/tmp"]
875      * splitPath( "C:/home:C:/tmp" ) = ["C:/home", "C:/tmp"]
876      * splitPath( "C:/home;C:/tmp" ) = ["C:/home", "C:/tmp"]
877      * </pre>
878      *
879      * @param path which can contain multiple paths separated with a colon (<code>:</code>) or a semi-colon
880      *            (<code>;</code>), platform independent. Could be null.
881      * @return the path splitted by colon or semi-colon or <code>null</code> if path was <code>null</code>.
882      * @since 2.6.1
883      */
884     protected static String[] splitPath(final String path) {
885         if (path == null) {
886             return null;
887         }
888 
889         List<String> subpaths = new ArrayList<>();
890         PathTokenizer pathTokenizer = new PathTokenizer(path);
891         while (pathTokenizer.hasMoreTokens()) {
892             subpaths.add(pathTokenizer.nextToken());
893         }
894 
895         return subpaths.toArray(new String[0]);
896     }
897 
898     /**
899      * Unify the given path with the current System path separator, to be platform independent. Examples:
900      *
901      * <pre>
902      * unifyPathSeparator( "/home:/tmp" ) = "/home:/tmp" (Solaris box)
903      * unifyPathSeparator( "/home:/tmp" ) = "/home;/tmp" (Windows box)
904      * </pre>
905      *
906      * @param path which can contain multiple paths by separating them with a colon (<code>:</code>) or a semi-colon
907      *            (<code>;</code>), platform independent. Could be null.
908      * @return the same path but separated with the current System path separator or <code>null</code> if path was
909      *         <code>null</code>.
910      * @since 2.6.1
911      * @see #splitPath(String)
912      * @see File#pathSeparator
913      */
914     protected static String unifyPathSeparator(final String path) {
915         if (path == null) {
916             return null;
917         }
918 
919         return String.join(File.pathSeparator, splitPath(path));
920     }
921 
922     // ----------------------------------------------------------------------
923     // private methods
924     // ----------------------------------------------------------------------
925 
926     /**
927      * @param jarFile not null
928      * @return all class names from the given jar file.
929      * @throws IOException if any or if the jarFile is null or doesn't exist.
930      */
931     private static List<String> getClassNamesFromJar(File jarFile) throws IOException {
932         if (jarFile == null || !jarFile.exists() || !jarFile.isFile()) {
933             throw new IOException("The jar '" + jarFile + "' doesn't exist or is not a file.");
934         }
935 
936         List<String> classes = new ArrayList<>();
937         Pattern pattern = Pattern.compile("(?i)^(META-INF/versions/(?<v>[0-9]+)/)?(?<n>.+)[.]class$");
938         try (JarInputStream jarStream = new JarInputStream(Files.newInputStream(jarFile.toPath()))) {
939             for (JarEntry jarEntry = jarStream.getNextJarEntry();
940                     jarEntry != null;
941                     jarEntry = jarStream.getNextJarEntry()) {
942                 Matcher matcher = pattern.matcher(jarEntry.getName());
943                 if (matcher.matches()) {
944                     String version = matcher.group("v");
945                     if ((version == null || version.isEmpty()) || JavaVersion.JAVA_VERSION.isAtLeast(version)) {
946                         String name = matcher.group("n");
947 
948                         classes.add(name.replaceAll("/", "\\."));
949                     }
950                 }
951 
952                 jarStream.closeEntry();
953             }
954         }
955 
956         return classes;
957     }
958 
959     /**
960      * @param log could be null
961      * @param invoker not null
962      * @param request not null
963      * @param invokerLog not null
964      * @param goals not null
965      * @param properties could be null
966      * @param mavenOpts could be null
967      * @return the invocation result
968      * @throws MavenInvocationException if any
969      * @since 2.6
970      */
971     private static InvocationResult invoke(
972             Log log,
973             Invoker invoker,
974             InvocationRequest request,
975             File invokerLog,
976             List<String> goals,
977             Properties properties,
978             String mavenOpts)
979             throws MavenInvocationException {
980         PrintStream ps;
981         OutputStream os = null;
982         if (invokerLog != null) {
983             if (log != null && log.isDebugEnabled()) {
984                 log.debug("Using " + invokerLog.getAbsolutePath() + " to log the invoker");
985             }
986 
987             try {
988                 if (!invokerLog.exists()) {
989                     // noinspection ResultOfMethodCallIgnored
990                     invokerLog.getParentFile().mkdirs();
991                 }
992                 os = new FileOutputStream(invokerLog);
993                 ps = new PrintStream(os, true, "UTF-8");
994             } catch (FileNotFoundException e) {
995                 if (log != null && log.isErrorEnabled()) {
996                     log.error("FileNotFoundException: " + e.getMessage() + ". Using System.out to log the invoker.");
997                 }
998                 ps = System.out;
999             } catch (UnsupportedEncodingException e) {
1000                 if (log != null && log.isErrorEnabled()) {
1001                     log.error("UnsupportedEncodingException: " + e.getMessage()
1002                             + ". Using System.out to log the invoker.");
1003                 }
1004                 ps = System.out;
1005             }
1006         } else {
1007             if (log != null && log.isDebugEnabled()) {
1008                 log.debug("Using System.out to log the invoker.");
1009             }
1010 
1011             ps = System.out;
1012         }
1013 
1014         if (mavenOpts != null) {
1015             request.setMavenOpts(mavenOpts);
1016         }
1017 
1018         InvocationOutputHandler outputHandler = new PrintStreamHandler(ps, false);
1019         request.setOutputHandler(outputHandler);
1020 
1021         try (OutputStream closeMe = os) {
1022             outputHandler.consumeLine("Invoking Maven for the goals: " + goals + " with "
1023                     + (properties == null ? "no properties" : "properties=" + properties));
1024             outputHandler.consumeLine("");
1025             outputHandler.consumeLine("M2_HOME=" + getMavenHome(log));
1026             outputHandler.consumeLine("MAVEN_OPTS=" + getMavenOpts(log));
1027             outputHandler.consumeLine("JAVA_HOME=" + getJavaHome(log));
1028             outputHandler.consumeLine("JAVA_OPTS=" + getJavaOpts(log));
1029             outputHandler.consumeLine("");
1030             return invoker.execute(request);
1031         } catch (IOException ioe) {
1032             throw new MavenInvocationException("IOException while consuming invocation output", ioe);
1033         }
1034     }
1035 
1036     /**
1037      * @param log a logger could be null
1038      * @return the Maven home defined in the <code>maven.home</code> system property
1039      *         or null if never set.
1040      * @since 2.6
1041      */
1042     private static String getMavenHome(Log log) {
1043         String mavenHome = System.getProperty("maven.home");
1044 
1045         File m2Home = new File(mavenHome);
1046         if (!m2Home.exists()) {
1047             if (log != null && log.isErrorEnabled()) {
1048                 log.error("Cannot find Maven application directory. Specify 'maven.home' system property.");
1049             }
1050         }
1051 
1052         return mavenHome;
1053     }
1054 
1055     /**
1056      * @param log a logger could be null
1057      * @return the <code>MAVEN_OPTS</code> env variable value
1058      * @since 2.6
1059      */
1060     private static String getMavenOpts(Log log) {
1061         return CommandLineUtils.getSystemEnvVars().getProperty("MAVEN_OPTS");
1062     }
1063 
1064     /**
1065      * @param log a logger could be null
1066      * @return the <code>JAVA_HOME</code> from System.getProperty( "java.home" ) By default,
1067      *         <code>System.getProperty( "java.home" ) = JRE_HOME</code> and <code>JRE_HOME</code> should be in the
1068      *         <code>JDK_HOME</code>
1069      * @since 2.6
1070      */
1071     private static File getJavaHome(Log log) {
1072         File javaHome = null;
1073 
1074         String javaHomeValue = CommandLineUtils.getSystemEnvVars().getProperty("JAVA_HOME");
1075 
1076         // if maven.home is set, we can assume JAVA_HOME must be used for testing
1077         if (System.getProperty("maven.home") == null || javaHomeValue == null) {
1078             // JEP220 (Java9) restructured the JRE/JDK runtime image
1079             if (SystemUtils.IS_OS_MAC_OSX || JavaVersion.JAVA_VERSION.isAtLeast("9")) {
1080                 javaHome = SystemUtils.getJavaHome();
1081             } else {
1082                 javaHome = new File(SystemUtils.getJavaHome(), "..");
1083             }
1084         }
1085 
1086         if (javaHome == null || !javaHome.exists()) {
1087             javaHome = new File(javaHomeValue);
1088         }
1089 
1090         if (javaHome == null || !javaHome.exists()) {
1091             if (log != null && log.isErrorEnabled()) {
1092                 log.error("Cannot find Java application directory. Either specify 'java.home' system property, or "
1093                         + "JAVA_HOME environment variable.");
1094             }
1095         }
1096 
1097         return javaHome;
1098     }
1099 
1100     /**
1101      * @param log a logger could be null
1102      * @return the <code>JAVA_OPTS</code> env variable value
1103      * @since 2.6
1104      */
1105     private static String getJavaOpts(Log log) {
1106         return CommandLineUtils.getSystemEnvVars().getProperty("JAVA_OPTS");
1107     }
1108 
1109     /**
1110      * A Path tokenizer takes a path and returns the components that make up that path. The path can use path separators
1111      * of either ':' or ';' and file separators of either '/' or '\'.
1112      *
1113      * @version revision 439418 taken on 2009-09-12 from Ant Project (see
1114      *          http://svn.apache.org/repos/asf/ant/core/trunk/src/main/org/apache/tools/ant/PathTokenizer.java)
1115      */
1116     private static class PathTokenizer {
1117         /**
1118          * A tokenizer to break the string up based on the ':' or ';' separators.
1119          */
1120         private StringTokenizer tokenizer;
1121 
1122         /**
1123          * A String which stores any path components which have been read ahead due to DOS filesystem compensation.
1124          */
1125         private String lookahead = null;
1126 
1127         /**
1128          * Flag to indicate whether or not we are running on a platform with a DOS style filesystem
1129          */
1130         private boolean dosStyleFilesystem;
1131 
1132         /**
1133          * Constructs a path tokenizer for the specified path.
1134          *
1135          * @param path The path to tokenize. Must not be <code>null</code>.
1136          */
1137         PathTokenizer(String path) {
1138             tokenizer = new StringTokenizer(path, ":;", false);
1139             dosStyleFilesystem = File.pathSeparatorChar == ';';
1140         }
1141 
1142         /**
1143          * Tests if there are more path elements available from this tokenizer's path. If this method returns
1144          * <code>true</code>, then a subsequent call to nextToken will successfully return a token.
1145          *
1146          * @return <code>true</code> if and only if there is at least one token in the string after the current
1147          *         position; <code>false</code> otherwise.
1148          */
1149         public boolean hasMoreTokens() {
1150             return lookahead != null || tokenizer.hasMoreTokens();
1151         }
1152 
1153         /**
1154          * Returns the next path element from this tokenizer.
1155          *
1156          * @return the next path element from this tokenizer.
1157          * @exception NoSuchElementException if there are no more elements in this tokenizer's path.
1158          */
1159         public String nextToken() throws NoSuchElementException {
1160             String token;
1161             if (lookahead != null) {
1162                 token = lookahead;
1163                 lookahead = null;
1164             } else {
1165                 token = tokenizer.nextToken().trim();
1166             }
1167 
1168             if (token.length() == 1
1169                     && Character.isLetter(token.charAt(0))
1170                     && dosStyleFilesystem
1171                     && tokenizer.hasMoreTokens()) {
1172                 // we are on a dos style system so this path could be a drive
1173                 // spec. We look at the next token
1174                 String nextToken = tokenizer.nextToken().trim();
1175                 if (nextToken.startsWith("\\") || nextToken.startsWith("/")) {
1176                     // we know we are on a DOS style platform and the next path
1177                     // starts with a slash or backslash, so we know this is a
1178                     // drive spec
1179                     token += ":" + nextToken;
1180                 } else {
1181                     // store the token just read for next time
1182                     lookahead = nextToken;
1183                 }
1184             }
1185             return token.trim();
1186         }
1187     }
1188 
1189     /**
1190      * Ignores line like 'Picked up JAVA_TOOL_OPTIONS: ...' as can happen on CI servers.
1191      *
1192      * @author Robert Scholte
1193      * @since 3.0.1
1194      */
1195     protected static class JavadocOutputStreamConsumer extends CommandLineUtils.StringStreamConsumer {
1196         @Override
1197         public void consumeLine(String line) {
1198             if (!line.startsWith("Picked up ")) {
1199                 super.consumeLine(line);
1200             }
1201         }
1202     }
1203 
1204     static List<String> toList(String src) {
1205         return toList(src, null, null);
1206     }
1207 
1208     static List<String> toList(String src, String elementPrefix, String elementSuffix) {
1209         if (src == null || src.isEmpty()) {
1210             return null;
1211         }
1212 
1213         List<String> result = new ArrayList<>();
1214 
1215         StringTokenizer st = new StringTokenizer(src, "[,:;]");
1216         StringBuilder sb = new StringBuilder(256);
1217         while (st.hasMoreTokens()) {
1218             sb.setLength(0);
1219             if (elementPrefix != null && !elementPrefix.isEmpty()) {
1220                 sb.append(elementPrefix);
1221             }
1222 
1223             sb.append(st.nextToken());
1224 
1225             if (elementSuffix != null && !elementSuffix.isEmpty()) {
1226                 sb.append(elementSuffix);
1227             }
1228 
1229             result.add(sb.toString().trim());
1230         }
1231 
1232         return result;
1233     }
1234 
1235     static <T> List<T> toList(T[] multiple) {
1236         return toList(null, multiple);
1237     }
1238 
1239     static <T> List<T> toList(T single, T[] multiple) {
1240         if (single == null && (multiple == null || multiple.length < 1)) {
1241             return null;
1242         }
1243 
1244         List<T> result = new ArrayList<>();
1245         if (single != null) {
1246             result.add(single);
1247         }
1248 
1249         if (multiple != null && multiple.length > 0) {
1250             result.addAll(Arrays.asList(multiple));
1251         }
1252 
1253         return result;
1254     }
1255 
1256     // TODO: deprecate in favor of Path.relativize
1257     public static String toRelative(File basedir, String absolutePath) {
1258         String relative;
1259 
1260         absolutePath = absolutePath.replace('\\', '/');
1261         String basedirPath = basedir.getAbsolutePath().replace('\\', '/');
1262 
1263         if (absolutePath.startsWith(basedirPath)) {
1264             relative = absolutePath.substring(basedirPath.length());
1265             if (relative.startsWith("/")) {
1266                 relative = relative.substring(1);
1267             }
1268             if (relative.length() <= 0) {
1269                 relative = ".";
1270             }
1271         } else {
1272             relative = absolutePath;
1273         }
1274 
1275         return relative;
1276     }
1277 
1278     /**
1279      * Convenience method to determine that a collection is not empty or null.
1280      * @param collection the collection to verify
1281      * @return {@code true} if not {@code null} and not empty, otherwise {@code false}
1282      */
1283     public static boolean isNotEmpty(final Collection<?> collection) {
1284         return collection != null && !collection.isEmpty();
1285     }
1286 
1287     /**
1288      * Convenience method to determine that a collection is empty or null.
1289      * @param collection the collection to verify
1290      * @return {@code true} if {@code null} or empty, otherwise {@code false}
1291      */
1292     public static boolean isEmpty(final Collection<?> collection) {
1293         return collection == null || collection.isEmpty();
1294     }
1295 
1296     /**
1297      * Execute an HTTP request to the given URL, follow redirects, and return the last redirect location. For URLs
1298      * that aren't http/https, this does nothing and simply returns the given URL unchanged.
1299      *
1300      * @param url URL
1301      * @param settings Maven settings
1302      * @return final URL after all redirects have been followed
1303      * @throws IOException if there was an error during the HTTP request
1304      */
1305     protected static URL getRedirectUrl(URL url, Settings settings) throws IOException {
1306         String protocol = url.getProtocol();
1307         if (!"http".equals(protocol) && !"https".equals(protocol)) {
1308             return url;
1309         }
1310 
1311         try (CloseableHttpClient httpClient = createHttpClient(settings, url)) {
1312             HttpClientContext httpContext = HttpClientContext.create();
1313             HttpGet httpMethod = new HttpGet(url.toString());
1314             HttpResponse response = httpClient.execute(httpMethod, httpContext);
1315             int status = response.getStatusLine().getStatusCode();
1316             if (status != HttpStatus.SC_OK) {
1317                 throw new FileNotFoundException(
1318                         "Unexpected HTTP status code " + status + " getting resource " + url.toExternalForm() + ".");
1319             }
1320 
1321             List<URI> redirects = httpContext.getRedirectLocations();
1322 
1323             if (isEmpty(redirects)) {
1324                 return url;
1325             } else {
1326                 URI last = redirects.get(redirects.size() - 1);
1327 
1328                 // URI must refer to directory, so prevent redirects to index.html
1329                 // see https://issues.apache.org/jira/browse/MJAVADOC-539
1330                 String truncate = "index.html";
1331                 if (last.getPath().endsWith("/" + truncate)) {
1332                     try {
1333                         String fixedPath =
1334                                 last.getPath().substring(0, last.getPath().length() - truncate.length());
1335                         last = new URI(
1336                                 last.getScheme(), last.getAuthority(), fixedPath, last.getQuery(), last.getFragment());
1337                     } catch (URISyntaxException ex) {
1338                         // not supposed to happen, but when it does just keep the last URI
1339                     }
1340                 }
1341                 return last.toURL();
1342             }
1343         }
1344     }
1345 
1346     /**
1347      * Validates an <code>URL</code> to point to a valid <code>package-list</code> resource.
1348      *
1349      * @param url The URL to validate.
1350      * @param settings The user settings used to configure the connection to the URL or {@code null}.
1351      * @param validateContent <code>true</code> to validate the content of the <code>package-list</code> resource;
1352      *            <code>false</code> to only check the existence of the <code>package-list</code> resource.
1353      * @return <code>true</code> if <code>url</code> points to a valid <code>package-list</code> resource;
1354      *         <code>false</code> else.
1355      * @throws IOException if reading the resource fails.
1356      * @see #createHttpClient(org.apache.maven.settings.Settings, java.net.URL)
1357      * @since 2.8
1358      */
1359     protected static boolean isValidPackageList(URL url, Settings settings, boolean validateContent)
1360             throws IOException {
1361         if (url == null) {
1362             throw new IllegalArgumentException("The url is null");
1363         }
1364 
1365         try (BufferedReader reader = getReader(url, settings)) {
1366             if (validateContent) {
1367                 for (String line = reader.readLine(); line != null; line = reader.readLine()) {
1368                     if (!isValidPackageName(line)) {
1369                         return false;
1370                     }
1371                 }
1372             }
1373             return true;
1374         }
1375     }
1376 
1377     protected static boolean isValidElementList(URL url, Settings settings, boolean validateContent)
1378             throws IOException {
1379         if (url == null) {
1380             throw new IllegalArgumentException("The url is null");
1381         }
1382 
1383         try (BufferedReader reader = getReader(url, settings)) {
1384             if (validateContent) {
1385                 for (String line = reader.readLine(); line != null; line = reader.readLine()) {
1386                     if (line.startsWith("module:")) {
1387                         continue;
1388                     }
1389 
1390                     if (!isValidPackageName(line)) {
1391                         return false;
1392                     }
1393                 }
1394             }
1395             return true;
1396         }
1397     }
1398 
1399     private static BufferedReader getReader(URL url, Settings settings) throws IOException {
1400         BufferedReader reader = null;
1401 
1402         if ("file".equals(url.getProtocol())) {
1403             // Intentionally using the platform default encoding here since this is what Javadoc uses internally.
1404             reader = new BufferedReader(new InputStreamReader(url.openStream()));
1405         } else {
1406             // http, https...
1407             final CloseableHttpClient httpClient = createHttpClient(settings, url);
1408 
1409             final HttpGet httpMethod = new HttpGet(url.toString());
1410 
1411             HttpResponse response;
1412             HttpClientContext httpContext = HttpClientContext.create();
1413             try {
1414                 response = httpClient.execute(httpMethod, httpContext);
1415             } catch (SocketTimeoutException e) {
1416                 // could be a sporadic failure, one more retry before we give up
1417                 response = httpClient.execute(httpMethod, httpContext);
1418             }
1419 
1420             int status = response.getStatusLine().getStatusCode();
1421             if (status != HttpStatus.SC_OK) {
1422                 throw new FileNotFoundException(
1423                         "Unexpected HTTP status code " + status + " getting resource " + url.toExternalForm() + ".");
1424             } else {
1425                 int pos = url.getPath().lastIndexOf('/');
1426                 List<URI> redirects = httpContext.getRedirectLocations();
1427                 if (pos >= 0 && isNotEmpty(redirects)) {
1428                     URI location = redirects.get(redirects.size() - 1);
1429                     String suffix = url.getPath().substring(pos);
1430                     // Redirections shall point to the same file, e.g. /package-list
1431                     if (!location.getPath().endsWith(suffix)) {
1432                         throw new FileNotFoundException(url.toExternalForm() + " redirects to "
1433                                 + location.toURL().toExternalForm() + ".");
1434                     }
1435                 }
1436             }
1437 
1438             // Intentionally using the platform default encoding here since this is what Javadoc uses internally.
1439             reader = new BufferedReader(
1440                     new InputStreamReader(response.getEntity().getContent())) {
1441                 @Override
1442                 public void close() throws IOException {
1443                     super.close();
1444 
1445                     if (httpMethod != null) {
1446                         httpMethod.releaseConnection();
1447                     }
1448                     if (httpClient != null) {
1449                         httpClient.close();
1450                     }
1451                 }
1452             };
1453         }
1454 
1455         return reader;
1456     }
1457 
1458     private static boolean isValidPackageName(String str) {
1459         if (str == null || str.isEmpty()) {
1460             // unnamed package is valid (even if bad practice :) )
1461             return true;
1462         }
1463 
1464         int idx;
1465         while ((idx = str.indexOf('.')) != -1) {
1466             if (!isValidClassName(str.substring(0, idx))) {
1467                 return false;
1468             }
1469 
1470             str = str.substring(idx + 1);
1471         }
1472 
1473         return isValidClassName(str);
1474     }
1475 
1476     private static boolean isValidClassName(String str) {
1477         if ((str == null || str.isEmpty()) || !Character.isJavaIdentifierStart(str.charAt(0))) {
1478             return false;
1479         }
1480 
1481         for (int i = str.length() - 1; i > 0; i--) {
1482             if (!Character.isJavaIdentifierPart(str.charAt(i))) {
1483                 return false;
1484             }
1485         }
1486 
1487         return true;
1488     }
1489 
1490     /**
1491      * Creates a new {@code HttpClient} instance.
1492      *
1493      * @param settings The settings to use for setting up the client or {@code null}.
1494      * @param url The {@code URL} to use for setting up the client or {@code null}.
1495      * @return A new {@code HttpClient} instance.
1496      * @see #DEFAULT_TIMEOUT
1497      * @since 2.8
1498      */
1499     private static CloseableHttpClient createHttpClient(Settings settings, URL url) {
1500         HttpClientBuilder builder = HttpClients.custom();
1501 
1502         Registry<ConnectionSocketFactory> csfRegistry = RegistryBuilder.<ConnectionSocketFactory>create()
1503                 .register("http", PlainConnectionSocketFactory.getSocketFactory())
1504                 .register("https", SSLConnectionSocketFactory.getSystemSocketFactory())
1505                 .build();
1506 
1507         builder.setConnectionManager(new PoolingHttpClientConnectionManager(csfRegistry));
1508         builder.setDefaultRequestConfig(RequestConfig.custom()
1509                 .setSocketTimeout(DEFAULT_TIMEOUT)
1510                 .setConnectTimeout(DEFAULT_TIMEOUT)
1511                 .setCircularRedirectsAllowed(true)
1512                 .setCookieSpec(CookieSpecs.IGNORE_COOKIES)
1513                 .build());
1514 
1515         // Some web servers don't allow the default user-agent sent by httpClient
1516         builder.setUserAgent("Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)");
1517 
1518         // Some server reject requests that do not have an Accept header
1519         builder.setDefaultHeaders(Collections.singletonList(new BasicHeader(HttpHeaders.ACCEPT, "*/*")));
1520 
1521         if (settings != null && settings.getActiveProxy() != null) {
1522             Proxy activeProxy = settings.getActiveProxy();
1523 
1524             ProxyInfo proxyInfo = new ProxyInfo();
1525             proxyInfo.setNonProxyHosts(activeProxy.getNonProxyHosts());
1526 
1527             String activeProxyHost = activeProxy.getHost();
1528             if (activeProxyHost != null
1529                     && !activeProxyHost.isEmpty()
1530                     && (url == null || !ProxyUtils.validateNonProxyHosts(proxyInfo, url.getHost()))) {
1531                 HttpHost proxy = new HttpHost(activeProxy.getHost(), activeProxy.getPort());
1532                 builder.setProxy(proxy);
1533 
1534                 String activeProxyUsername = activeProxy.getUsername();
1535                 if (activeProxyUsername != null
1536                         && !activeProxyUsername.isEmpty()
1537                         && activeProxy.getPassword() != null) {
1538                     Credentials credentials =
1539                             new UsernamePasswordCredentials(activeProxyUsername, activeProxy.getPassword());
1540 
1541                     CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
1542                     credentialsProvider.setCredentials(AuthScope.ANY, credentials);
1543                     builder.setDefaultCredentialsProvider(credentialsProvider);
1544                 }
1545             }
1546         }
1547         return builder.build();
1548     }
1549 
1550     static boolean equalsIgnoreCase(String value, String... strings) {
1551         for (String s : strings) {
1552             if (s.equalsIgnoreCase(value)) {
1553                 return true;
1554             }
1555         }
1556         return false;
1557     }
1558 
1559     static boolean equals(String value, String... strings) {
1560         for (String s : strings) {
1561             if (s.equals(value)) {
1562                 return true;
1563             }
1564         }
1565         return false;
1566     }
1567 }