Package org.apache.maven.plugins.javadoc

Class JavadocUtil

java.lang.Object
org.apache.maven.plugins.javadoc.JavadocUtil
public class JavadocUtil extends Object
Set of utilities methods for Javadoc.
Since:
2.4

  • Field Details

    • DEFAULT_TIMEOUT

      public static final int DEFAULT_TIMEOUT
      The default timeout used when fetching a URL in milliseconds. The default value is 2000.
      See Also:

    • ERROR_INIT_VM

      protected static final String ERROR_INIT_VM
      Error message when VM could not be started using invoker.
      See Also:

    • EXTRACT_JAVADOC_VERSION_PATTERN

      private static final Pattern EXTRACT_JAVADOC_VERSION_PATTERN

    • PARSE_JAVADOC_MEMORY_PATTERN_0

      private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_0

    • PARSE_JAVADOC_MEMORY_PATTERN_1

      private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_1

    • PARSE_JAVADOC_MEMORY_PATTERN_2

      private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_2

    • PARSE_JAVADOC_MEMORY_PATTERN_3

      private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_3

    • PARSE_JAVADOC_MEMORY_PATTERN_4

      private static final Pattern PARSE_JAVADOC_MEMORY_PATTERN_4

  • Constructor Details

    • JavadocUtil

      public JavadocUtil()

  • Method Details

    • prunePaths

      public static Collection<Path> prunePaths(org.apache.maven.project.MavenProject project, Collection<String> paths, boolean includeFiles)
      Method that removes invalid classpath elements in the specified paths. Note: All elements in paths could be absolute or relative against the project's base directory. When pruning classpath elements, you can optionally include files in the result, otherwise only directories are permitted.
      Parameters:
      project - the current Maven project not null
      paths - the collection of paths that will be validated
      includeFiles - whether to include files in the result as well
      Returns:
      a list of valid classpath elements as absolute paths

    • pruneDirs

      public static Collection<Path> pruneDirs(org.apache.maven.project.MavenProject project, Collection<String> dirs)
      Method that removes the invalid classpath directories in the specified directories. Note: All elements in dirs could be absolute or relative against the project's base directory.
      Parameters:
      project - the current Maven project not null
      dirs - the collection of directories that will be validated
      Returns:
      a list of valid classpath elements as absolute paths

    • pruneFiles

      protected static List<String> pruneFiles(Collection<String> files)
      Method that removes the invalid files in the specified files. Note: All elements in files should be an absolute String path.
      Parameters:
      files - the list of String files paths that will be validated.
      Returns:
      a List of valid File objects.

    • shouldPruneFile

      public static boolean shouldPruneFile(String f, List<String> pruned)
      Determine whether a file should be excluded from the provided list of paths, based on whether it exists and is already present in the list.
      Parameters:
      f - the files
      pruned - the list of pruned files
      Returns:
      true if the file could be pruned, false otherwise

    • getExcludedPackages

      protected static List<String> getExcludedPackages(Collection<Path> sourcePaths, Collection<String> excludedPackages)
      Method that gets all the source files to be excluded from the javadoc on the given source paths.
      Parameters:
      sourcePaths - the path to the source files
      excludedPackages - the package names to be excluded in the javadoc
      Returns:
      a List of the packages to be excluded in the generated javadoc

    • quotedArgument

      protected static String quotedArgument(String value)
      Convenience method to wrap a command line option-argument in single quotes (i.e. '). Intended for values which may contain whitespace.
      Line feeds (i.e. \n) are replaced with spaces, and single quotes are backslash escaped.
      Parameters:
      value - the option-argument
      Returns:
      quoted option-argument

    • quotedPathArgument

      protected static String quotedPathArgument(String value)
      Convenience method to format a path argument so that it is properly interpreted by the javadoc tool. Intended for path values which may contain whitespaces.
      Parameters:
      value - the argument value.
      Returns:
      path argument with quote

    • copyJavadocResources

      protected static void copyJavadocResources(File outputDirectory, File javadocDir, String excludedocfilessubdir) throws IOException
      Convenience method that copies all doc-files directories from javadocDir to the outputDirectory.
      Parameters:
      outputDirectory - the output directory
      javadocDir - the javadoc directory
      excludedocfilessubdir - the excludedocfilessubdir parameter
      Throws:
      IOException - if any
      Since:
      2.5

    • getIncludedFiles

      protected static List<String> getIncludedFiles(File sourceDirectory, String[] fileList, Collection<String> excludePackages)
      Method that gets the files or classes that would be included in the javadocs using the subpackages parameter.
      Parameters:
      sourceDirectory - the directory where the source files are located
      fileList - the list of all relative files found in the sourceDirectory
      excludePackages - package names to be excluded in the javadoc
      Returns:
      a StringBuilder that contains the appended file names of the files to be included in the javadoc

    • getExcludedPackages

      protected static Collection<String> getExcludedPackages(Path sourceDirectory, Collection<String> excludePackagenames)
      Method that gets the complete package names (including subpackages) of the packages that were defined in the excludePackageNames parameter.
      Parameters:
      sourceDirectory - the directory where the source files are located
      excludePackagenames - package names to be excluded in the javadoc
      Returns:
      the package names to be excluded

    • getFilesFromSource

      protected static List<String> getFilesFromSource(File sourceDirectory, List<String> sourceFileIncludes, List<String> sourceFileExcludes, Collection<String> excludePackages)
      Convenience method that gets the files to be included in the javadoc.
      Parameters:
      sourceDirectory - the directory where the source files are located
      sourceFileIncludes - files to include
      sourceFileExcludes - files to exclude
      excludePackages - packages to be excluded from the javadocs
      Returns:
      the files from which javadoc should be generated

    • getJavadocVersion

      protected static org.codehaus.plexus.languages.java.version.JavaVersion getJavadocVersion(File javadocExe) throws IOException, org.codehaus.plexus.util.cli.CommandLineException, IllegalArgumentException
      Call the Javadoc tool and parse its output to find its version, i.e.: 
       javadoc.exe( or.sh ) - J - version
      Parameters:
      javadocExe - not null file
      Returns:
      the javadoc version as float
      Throws:
      IOException - if javadocExe is null, doesn't exist or is not a file
      org.codehaus.plexus.util.cli.CommandLineException - if any
      IllegalArgumentException - if no output was found in the command line
      PatternSyntaxException - if the output contains a syntax error in the regular-expression pattern.
      See Also:

    • extractJavadocVersion

      protected static String extractJavadocVersion(String output)
      Parse the output of 'javadoc -J-version' and return the javadoc version recognized.
      Here are some output for 'javadoc -J-version' depending on the JDK used:
      Output of 'javadoc -J-version' per JDK
      JDK Output for 'javadoc -J-version'
      Sun 1.4 java full version "1.4.2_12-b03"
      Sun 1.5 java full version "1.5.0_07-164"
      IBM 1.4 javadoc full version "J2RE 1.4.2 IBM Windows 32 build cn1420-20040626"
      IBM 1.5 (French JVM) javadoc version complète de "J2RE 1.5.0 IBM Windows 32 build pwi32pdev-20070426a"
      FreeBSD 1.5 java full version "diablo-1.5.0-b01"
      BEA jrockit 1.5 java full version "1.5.0_11-b03"
      Parameters:
      output - of 'javadoc -J-version'
      Returns:
      the version of the javadoc for the output, only digits and dots
      Throws:
      PatternSyntaxException - if the output doesn't match the output pattern (?s).*?[^a-zA-Z]([0-9]+\\.?[0-9]*)(\\.([0-9]+))?.*.
      NullPointerException - if the output is null
      IllegalArgumentException - if the output is empty

    • parseJavadocMemory

      protected static String parseJavadocMemory(String memory)
      Parse a memory string which be used in the JVM arguments -Xms or -Xmx.
      Here are some supported memory string depending on the JDK used:
      Memory argument support per JDK
      JDK Memory argument support for -Xms or -Xmx
      SUN 1024k | 128m | 1g | 1t
      IBM 1024k | 1024b | 128m | 128mb | 1g | 1gb
      BEA 1024k | 1024kb | 128m | 128mb | 1g | 1gb
      Parameters:
      memory - the memory to be parsed, not null.
      Returns:
      the memory parsed with a supported unit. If no unit is specified in the memory argument, the default unit is m. The units g | gb or t | tb will be converted in m.
      Throws:
      NullPointerException - if the memory argument is null
      IllegalArgumentException - if the memory argument doesn't match any pattern.

    • validateEncoding

      protected static boolean validateEncoding(String charsetName)
      Validate if a charset is supported on this platform.
      Parameters:
      charsetName - the charsetName to check
      Returns:
      true if the given charset is supported by the JVM, false otherwise.

    • getTagletClassNames

      protected static List<String> getTagletClassNames(File jarFile) throws IOException, ClassNotFoundException, NoClassDefFoundError
      Auto-detect the class names of the implementation of com.sun.tools.doclets.Taglet class from a given jar file.
      Note: JAVA_HOME/lib/tools.jar is a requirement to find com.sun.tools.doclets.Taglet class.
      Parameters:
      jarFile - not null
      Returns:
      the list of com.sun.tools.doclets.Taglet class names from a given jarFile.
      Throws:
      IOException - if jarFile is invalid or not found, or if the JAVA_HOME/lib/tools.jar is not found.
      ClassNotFoundException - if any
      NoClassDefFoundError - if any

    • copyResource

      protected static void copyResource(URL url, File file) throws IOException
      Copy the given url to the given file.
      Parameters:
      url - not null url
      file - not null file where the url will be created
      Throws:
      IOException - if any
      Since:
      2.6

    • invokeMaven

      protected static void invokeMaven(org.apache.maven.plugin.logging.Log log, File localRepositoryDir, File projectFile, List<String> goals, Properties properties, File invokerLog, File globalSettingsFile, File userSettingsFile, File globalToolchainsFile, File userToolchainsFile) throws org.apache.maven.shared.invoker.MavenInvocationException
      Invoke Maven for the given project file with a list of goals and properties, the output will be in the invokerlog file.
      Note: the Maven Home should be defined in the maven.home Java system property or defined in M2_HOME system env variables.
      Parameters:
      log - a logger could be null.
      localRepositoryDir - the localRepository not null.
      projectFile - a not null project file.
      goals - a not null goals list.
      properties - the properties for the goals, could be null.
      invokerLog - the log file where the invoker will be written, if null using System.out.
      globalSettingsFile - reference to settings file, could be null.
      userSettingsFile - reference to user settings file, could be null.
      globalToolchainsFile - reference to toolchains file, could be null.
      userToolchainsFile - reference to user toolchains file, could be null.
      Throws:
      org.apache.maven.shared.invoker.MavenInvocationException - if any
      Since:
      2.6

    • readFile

      @Deprecated protected static String readFile(File javaFile, String encoding)
      Deprecated.
      use Files.readString(Path, Charset) in Java 11+ or new String(Files.readAllBytes(Path), Charset) in Java 8
      Read the given file and return the content or null if an IOException occurs.
      Parameters:
      javaFile - the file to read; not null
      encoding - a character set name; not null
      Returns:
      the content of the given file using the given encoding; null if an IOException occurs
      Throws:
      UnsupportedCharsetException - if the named charset is not supported
      NullPointerException - if the javaFile or encoding is null
      Since:
      2.6.1

    • splitPath

      protected static String[] splitPath(String path)
      Split the given path with colon and semicolon, to support Unix and Windows paths. Examples: 
       splitPath( "/home:/tmp" )     = ["/home", "/tmp"]
 splitPath( "/home;/tmp" )     = ["/home", "/tmp"]
 splitPath( "C:/home:C:/tmp" ) = ["C:/home", "C:/tmp"]
 splitPath( "C:/home;C:/tmp" ) = ["C:/home", "C:/tmp"]
      Parameters:
      path - which can contain multiple paths separated with a colon (:) or a semicolon (;), platform independent. Could be null.
      Returns:
      the path split by colon or semicolon or null if path was null.
      Since:
      2.6.1

    • unifyPathSeparator

      protected static String unifyPathSeparator(String path)
      Unify the given path with the current System path separator, to be platform independent. Examples: 
       unifyPathSeparator( "/home:/tmp" ) = "/home:/tmp" (Solaris box)
 unifyPathSeparator( "/home:/tmp" ) = "/home;/tmp" (Windows box)
      Parameters:
      path - which can contain multiple paths by separating them with a colon (:) or a semicolon (;), platform independent. Could be null.
      Returns:
      the same path but separated with the current System path separator or null if path was null.
      Since:
      2.6.1
      See Also:

    • getClassNamesFromJar

      private static List<String> getClassNamesFromJar(File jarFile) throws IOException
      Parameters:
      jarFile - not null
      Returns:
      all class names from the given jar file.
      Throws:
      IOException - if any or if the jarFile is null or doesn't exist.

    • invoke

      private static org.apache.maven.shared.invoker.InvocationResult invoke(org.apache.maven.plugin.logging.Log log, org.apache.maven.shared.invoker.Invoker invoker, org.apache.maven.shared.invoker.InvocationRequest request, File invokerLog, List<String> goals, Properties properties, String mavenOpts) throws org.apache.maven.shared.invoker.MavenInvocationException
      Parameters:
      log - could be null
      invoker - not null
      request - not null
      invokerLog - not null
      goals - not null
      properties - could be null
      mavenOpts - could be null
      Returns:
      the invocation result
      Throws:
      org.apache.maven.shared.invoker.MavenInvocationException - if any
      Since:
      2.6

    • getMavenHome

      private static String getMavenHome(org.apache.maven.plugin.logging.Log log)
      Parameters:
      log - a logger could be null
      Returns:
      the Maven home defined in the maven.home system property or null if never set.
      Since:
      2.6

    • getMavenOpts

      private static String getMavenOpts(org.apache.maven.plugin.logging.Log log)
      Parameters:
      log - a logger could be null
      Returns:
      the MAVEN_OPTS env variable value
      Since:
      2.6

    • getJavaHome

      private static File getJavaHome(org.apache.maven.plugin.logging.Log log)
      Parameters:
      log - a logger could be null
      Returns:
      the JAVA_HOME from System.getProperty( "java.home" ) By default, System.getProperty( "java.home" ) = JRE_HOME and JRE_HOME should be in the JDK_HOME
      Since:
      2.6

    • getJavaOpts

      private static String getJavaOpts(org.apache.maven.plugin.logging.Log log)
      Parameters:
      log - a logger could be null
      Returns:
      the JAVA_OPTS env variable value
      Since:
      2.6

    • toList

      static List<String> toList(String src)

    • toList

      static List<String> toList(String src, String elementPrefix, String elementSuffix)

    • toList

      static <T> List<T> toList(T[] multiple)

    • toList

      static <T> List<T> toList(T single, T[] multiple)

    • toRelative

      @Deprecated public static String toRelative(File basedir, String absolutePath)
      Deprecated.
      use Path.relativize(Path) () instead

    • isNotEmpty

      public static boolean isNotEmpty(Collection<?> collection)
      Convenience method to determine that a collection is not empty or null.
      Parameters:
      collection - the collection to verify
      Returns:
      true if not null and not empty, otherwise false

    • isEmpty

      public static boolean isEmpty(Collection<?> collection)
      Convenience method to determine that a collection is empty or null.
      Parameters:
      collection - the collection to verify
      Returns:
      true if null or empty, otherwise false

    • getRedirectUrl

      protected static URL getRedirectUrl(URL url, org.apache.maven.settings.Settings settings) throws IOException
      Execute an HTTP request to the given URL, follow redirects, and return the last redirect location. For URLs that aren't http/https, this does nothing and simply returns the given URL unchanged.
      Parameters:
      url - URL
      settings - Maven settings
      Returns:
      final URL after all redirects have been followed
      Throws:
      IOException - if there was an error during the HTTP request

    • isValidPackageList

      protected static boolean isValidPackageList(URL url, org.apache.maven.settings.Settings settings, boolean validateContent) throws IOException
      Validates an URL to point to a valid package-list resource.
      Parameters:
      url - The URL to validate.
      settings - The user settings used to configure the connection to the URL or null.
      validateContent - true to validate the content of the package-list resource; false to only check the existence of the package-list resource.
      Returns:
      true if url points to a valid package-list resource; false else.
      Throws:
      IOException - if reading the resource fails.
      Since:
      2.8
      See Also:

    • isValidElementList

      protected static boolean isValidElementList(URL url, org.apache.maven.settings.Settings settings, boolean validateContent) throws IOException
      Throws:
      IOException

    • getReader

      private static BufferedReader getReader(URL url, org.apache.maven.settings.Settings settings) throws IOException
      Throws:
      IOException

    • isValidPackageName

      private static boolean isValidPackageName(String str)

    • isValidClassName

      private static boolean isValidClassName(String str)

    • createHttpClient

      private static org.apache.http.impl.client.CloseableHttpClient createHttpClient(org.apache.maven.settings.Settings settings, URL url)
      Creates a new HttpClient instance.
      Parameters:
      settings - the settings to use for setting up the client or null
      url - the URL to use for setting up the client or null
      Returns:
      a new HttpClient instance
      Since:
      2.8
      See Also:

    • isNonProxyHost

      private static boolean isNonProxyHost(String nonProxyHosts, String targetHost)

    • equalsIgnoreCase

      static boolean equalsIgnoreCase(String value, String... strings)

    • equals

      static boolean equals(String value, String... strings)