Class JavadocUtil


  • public class JavadocUtil
    extends Object
    Set of utilities methods for Javadoc.
    Since:
    2.4
    Author:
    Vincent Siveton
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected static class  JavadocUtil.JavadocOutputStreamConsumer
      Ignores line like 'Picked up JAVA_TOOL_OPTIONS: ...' as can happen on CI servers.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int DEFAULT_TIMEOUT
      The default timeout used when fetching url, i.e.
      protected static String ERROR_INIT_VM
      Error message when VM could not be started using invoker.
    • Constructor Summary

      Constructors 
      Constructor Description
      JavadocUtil()  
    • Field Detail

      • DEFAULT_TIMEOUT

        public static final int DEFAULT_TIMEOUT
        The default timeout used when fetching url, i.e. 2000.
        See Also:
        Constant Field Values
      • ERROR_INIT_VM

        protected static final String ERROR_INIT_VM
        Error message when VM could not be started using invoker.
        See Also:
        Constant Field Values
    • Constructor Detail

      • JavadocUtil

        public JavadocUtil()
    • Method Detail

      • pruneDirs

        public static Collection<Path> pruneDirs​(org.apache.maven.project.MavenProject project,
                                                 Collection<String> dirs)
        Method that removes the invalid directories in the specified directories. Note: All elements in dirs could be an absolute or relative against the project's base directory String path.
        Parameters:
        project - the current Maven project not null
        dirs - the collection of String directories path that will be validated.
        Returns:
        a List of valid String directories 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 copy 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:
        a List of the packagenames 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(String)
      • extractJavadocVersion

        protected static String extractJavadocVersion​(String output)
                                               throws IllegalArgumentException
        Parse the output for 'javadoc -J-version' and return the javadoc version recognized.
        Here are some output for 'javadoc -J-version' depending the JDK used:
        Output for '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 - for 'javadoc -J-version'
        Returns:
        the version of the javadoc for the output, only digits and dots
        Throws:
        PatternSyntaxException - if the output doesn't match with the output pattern (?s).*?[^a-zA-Z]([0-9]+\\.?[0-9]*)(\\.([0-9]+))?.*.
        IllegalArgumentException - if the output is null
      • parseJavadocMemory

        protected static String parseJavadocMemory​(String memory)
                                            throws IllegalArgumentException
        Parse a memory string which be used in the JVM arguments -Xms or -Xmx.
        Here are some supported memory string depending 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 specified in the memory parameter, the default unit is m. The units g | gb or t | tb will be converted in m.
        Throws:
        IllegalArgumentException - if the memory parameter is null or 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 be 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)
                                   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.
        Throws:
        org.apache.maven.shared.invoker.MavenInvocationException - if any
        Since:
        2.6
      • readFile

        protected static String readFile​(File javaFile,
                                         String encoding)
        Read the given file and return the content or null if an IOException occurs.
        Parameters:
        javaFile - not null
        encoding - could be null
        Returns:
        the content with unified line separator of the given javaFile using the given encoding.
        Since:
        2.6.1
        See Also:
        FileUtils.fileRead(File, String)
      • splitPath

        protected static String[] splitPath​(String path)
        Split the given path with colon and semi-colon, to support Solaris and Windows path. 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 semi-colon (;), platform independent. Could be null.
        Returns:
        the path splitted by colon or semi-colon 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 semi-colon (;), 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:
        splitPath(String), File.pathSeparator
      • toRelative

        public static String toRelative​(File basedir,
                                        String absolutePath)
      • 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:
        createHttpClient(org.apache.maven.settings.Settings, java.net.URL)
      • isValidElementList

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