org.apache.maven.plugins.javadoc

Class JavadocUtil

java.lang.Object

org.apache.maven.plugins.javadoc.JavadocUtil

public class JavadocUtil
extends java.lang.Object

Set of utilities methods for Javadoc.

Since:

2.4

Version:

$Id: JavadocUtil.java 1801354 2017-07-09 08:49:46Z rfscholte $

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	JavadocUtil.JavadocOutputStreamConsumer Ignores line like 'Picked up JAVA_TOOL_OPTIONS: ...' as can happen on CI servers.
private static class	JavadocUtil.PathTokenizer A Path tokenizer takes a path and returns the components that make up that path.

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor and Description
JavadocUtil()

Method Summary

Modifier and Type	Method and Description
protected static void	addFilesFromSource(java.util.List<java.lang.String> files, java.io.File sourceDirectory, java.util.List<java.lang.String> sourceFileIncludes, java.util.List<java.lang.String> sourceFileExcludes, java.lang.String[] excludePackages) Convenience method that gets the files to be included in the javadoc.
protected static void	copyJavadocResources(java.io.File outputDirectory, java.io.File javadocDir, java.lang.String excludedocfilessubdir) Convenience method that copy all doc-files directories from javadocDir to the outputDirectory.
protected static void	copyResource(java.net.URL url, java.io.File file) Copy the given url to the given file.
private static org.apache.http.client.HttpClient	createHttpClient(org.apache.maven.settings.Settings settings, java.net.URL url) Creates a new HttpClient instance.
(package private) static boolean	equals(java.lang.String value, java.lang.String... strings)
(package private) static boolean	equalsIgnoreCase(java.lang.String value, java.lang.String... strings)
protected static java.lang.String	extractJavadocVersion(java.lang.String output) Parse the output for 'javadoc -J-version' and return the javadoc version recognized.
private static java.util.List<java.lang.String>	getClassNamesFromJar(java.io.File jarFile)
protected static java.util.List<java.lang.String>	getExcludedNames(java.util.Collection<java.lang.String> sourcePaths, java.lang.String[] subpackagesList, java.lang.String[] excludedPackages) Method that gets all the source files to be excluded from the javadoc on the given source paths.
protected static java.util.List<java.lang.String>	getExcludedPackages(java.lang.String sourceDirectory, java.lang.String[] excludePackagenames) Method that gets the complete package names (including subpackages) of the packages that were defined in the excludePackageNames parameter.
protected static java.util.List<java.lang.String>	getIncludedFiles(java.io.File sourceDirectory, java.lang.String[] fileList, java.lang.String[] excludePackages) Method that gets the files or classes that would be included in the javadocs using the subpackages parameter.
protected static org.codehaus.plexus.languages.java.version.JavaVersion	getJavadocVersion(java.io.File javadocExe) Call the Javadoc tool and parse its output to find its version, i.e.:
private static java.io.File	getJavaHome(org.apache.maven.plugin.logging.Log log)
private static java.lang.String	getJavaOpts(org.apache.maven.plugin.logging.Log log)
private static java.lang.String	getMavenHome(org.apache.maven.plugin.logging.Log log)
private static java.lang.String	getMavenOpts(org.apache.maven.plugin.logging.Log log)
protected static java.net.URL	getRedirectUrl(java.net.URL url, org.apache.maven.settings.Settings settings) Execute an Http request at the given URL, follows redirects, and returns the last redirect locations.
protected static java.util.List<java.lang.String>	getTagletClassNames(java.io.File jarFile) Auto-detect the class names of the implementation of com.sun.tools.doclets.Taglet class from a given jar file.
protected static java.lang.String	hideProxyPassword(java.lang.String cmdLine, org.apache.maven.settings.Settings settings) For security reasons, if an active proxy is defined and needs an authentication by username/password, hide the proxy password in the command line.
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, java.io.File invokerLog, java.util.List<java.lang.String> goals, java.util.Properties properties, java.lang.String mavenOpts)
protected static void	invokeMaven(org.apache.maven.plugin.logging.Log log, java.io.File localRepositoryDir, java.io.File projectFile, java.util.List<java.lang.String> goals, java.util.Properties properties, java.io.File invokerLog) Invoke Maven for the given project file with a list of goals and properties, the output will be in the invokerlog file.
static boolean	isEmpty(java.util.Collection<?> collection) Convenience method to determine that a collection is empty or null.
static boolean	isNotEmpty(java.util.Collection<?> collection) Convenience method to determine that a collection is not empty or null.
private static boolean	isValidClassName(java.lang.String str)
protected static boolean	isValidPackageList(java.net.URL url, org.apache.maven.settings.Settings settings, boolean validateContent) Validates an URL to point to a valid package-list resource.
private static boolean	isValidPackageName(java.lang.String str)
protected static java.lang.String	parseJavadocMemory(java.lang.String memory) Parse a memory string which be used in the JVM arguments -Xms or -Xmx.
static java.util.Collection<java.lang.String>	pruneDirs(org.apache.maven.project.MavenProject project, java.util.Collection<java.lang.String> dirs) Method that removes the invalid directories in the specified directories.
protected static java.util.List<java.lang.String>	pruneFiles(java.util.Collection<java.lang.String> files) Method that removes the invalid files in the specified files.
protected static java.lang.String	quotedArgument(java.lang.String value) Convenience method to wrap an argument value in single quotes (i.e.
protected static java.lang.String	quotedPathArgument(java.lang.String value) Convenience method to format a path argument so that it is properly interpreted by the javadoc tool.
protected static java.lang.String	readFile(java.io.File javaFile, java.lang.String encoding) Read the given file and return the content or null if an IOException occurs.
static boolean	shouldPruneFile(java.lang.String f, java.util.List<java.lang.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.
protected static java.lang.String[]	splitPath(java.lang.String path) Split the given path with colon and semi-colon, to support Solaris and Windows path.
(package private) static java.util.List<java.lang.String>	toList(java.lang.String src)
(package private) static java.util.List<java.lang.String>	toList(java.lang.String src, java.lang.String elementPrefix, java.lang.String elementSuffix)
(package private) static <T> java.util.List<T>	toList(T[] multiple)
(package private) static <T> java.util.List<T>	toList(T single, T[] multiple)
static java.lang.String	toRelative(java.io.File basedir, java.lang.String absolutePath)
protected static java.lang.String	unifyPathSeparator(java.lang.String path) Unify the given path with the current System path separator, to be platform independent.
protected static boolean	validateEncoding(java.lang.String charsetName) Validate if a charset is supported on this platform.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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 java.lang.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 java.util.Collection<java.lang.String> pruneDirs(org.apache.maven.project.MavenProject project,
                                                               java.util.Collection<java.lang.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 java.util.List<java.lang.String> pruneFiles(java.util.Collection<java.lang.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(java.lang.String f,
                                      java.util.List<java.lang.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.

getExcludedNames

protected static java.util.List<java.lang.String> getExcludedNames(java.util.Collection<java.lang.String> sourcePaths,
                                                                   java.lang.String[] subpackagesList,
                                                                   java.lang.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

subpackagesList - list of subpackages to be included in the javadoc

excludedPackages - the package names to be excluded in the javadoc

Returns:

a List of the source files to be excluded in the generated javadoc

quotedArgument

protected static java.lang.String quotedArgument(java.lang.String value)

Convenience method to wrap an argument value in single quotes (i.e. '). Intended for values which may contain whitespaces.
To prevent javadoc error, the line separator (i.e. \n) are skipped.

Parameters:

value - the argument value.

Returns:

argument with quote

quotedPathArgument

protected static java.lang.String quotedPathArgument(java.lang.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(java.io.File outputDirectory,
                                           java.io.File javadocDir,
                                           java.lang.String excludedocfilessubdir)
                                    throws java.io.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:

java.io.IOException - if any

Since:

2.5

getIncludedFiles

protected static java.util.List<java.lang.String> getIncludedFiles(java.io.File sourceDirectory,
                                                                   java.lang.String[] fileList,
                                                                   java.lang.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 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 java.util.List<java.lang.String> getExcludedPackages(java.lang.String sourceDirectory,
                                                                      java.lang.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

addFilesFromSource

protected static void addFilesFromSource(java.util.List<java.lang.String> files,
                                         java.io.File sourceDirectory,
                                         java.util.List<java.lang.String> sourceFileIncludes,
                                         java.util.List<java.lang.String> sourceFileExcludes,
                                         java.lang.String[] excludePackages)

Convenience method that gets the files to be included in the javadoc.

Parameters:

sourceDirectory - the directory where the source files are located

files - the variable that contains the appended filenames of the files to be included in the javadoc

excludePackages - the packages to be excluded in the javadocs

sourceFileIncludes - files to include.

sourceFileExcludes - files to exclude.

getJavadocVersion

protected static org.codehaus.plexus.languages.java.version.JavaVersion getJavadocVersion(java.io.File javadocExe)
                                                                                   throws java.io.IOException,
                                                                                          org.codehaus.plexus.util.cli.CommandLineException,
                                                                                          java.lang.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:

java.io.IOException - if javadocExe is null, doesn't exist or is not a file

org.codehaus.plexus.util.cli.CommandLineException - if any

java.lang.IllegalArgumentException - if no output was found in the command line

java.util.regex.PatternSyntaxException - if the output contains a syntax error in the regular-expression pattern.

See Also:

extractJavadocVersion(String)

extractJavadocVersion

protected static java.lang.String extractJavadocVersion(java.lang.String output)
                                                 throws java.lang.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:

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:

java.util.regex.PatternSyntaxException - if the output doesn't match with the output pattern (?s).*?[^a-zA-Z]([0-9]+\\.?[0-9]*)(\\.([0-9]+))?.*.

java.lang.IllegalArgumentException - if the output is null

parseJavadocMemory

protected static java.lang.String parseJavadocMemory(java.lang.String memory)
                                              throws java.lang.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:

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:

java.lang.IllegalArgumentException - if the memory parameter is null or doesn't match any pattern.

validateEncoding

protected static boolean validateEncoding(java.lang.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.

hideProxyPassword

protected static java.lang.String hideProxyPassword(java.lang.String cmdLine,
                                                    org.apache.maven.settings.Settings settings)

For security reasons, if an active proxy is defined and needs an authentication by username/password, hide the proxy password in the command line.

Parameters:

cmdLine - a command line, not null

settings - the user settings

Returns:

the cmdline with '*' for the http.proxyPassword JVM property

getTagletClassNames

protected static java.util.List<java.lang.String> getTagletClassNames(java.io.File jarFile)
                                                               throws java.io.IOException,
                                                                      java.lang.ClassNotFoundException,
                                                                      java.lang.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:

java.io.IOException - if jarFile is invalid or not found, or if the JAVA_HOME/lib/tools.jar is not found.

java.lang.ClassNotFoundException - if any

java.lang.NoClassDefFoundError - if any

copyResource

protected static void copyResource(java.net.URL url,
                                   java.io.File file)
                            throws java.io.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:

java.io.IOException - if any

Since:

2.6

invokeMaven

protected static void invokeMaven(org.apache.maven.plugin.logging.Log log,
                                  java.io.File localRepositoryDir,
                                  java.io.File projectFile,
                                  java.util.List<java.lang.String> goals,
                                  java.util.Properties properties,
                                  java.io.File invokerLog)
                           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.

Throws:

org.apache.maven.shared.invoker.MavenInvocationException - if any

Since:

2.6

readFile

protected static java.lang.String readFile(java.io.File javaFile,
                                           java.lang.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 java.lang.String[] splitPath(java.lang.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 java.lang.String unifyPathSeparator(java.lang.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

getClassNamesFromJar

private static java.util.List<java.lang.String> getClassNamesFromJar(java.io.File jarFile)
                                                              throws java.io.IOException

Parameters:

jarFile - not null

Returns:

all class names from the given jar file.

Throws:

java.io.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,
                                                                       java.io.File invokerLog,
                                                                       java.util.List<java.lang.String> goals,
                                                                       java.util.Properties properties,
                                                                       java.lang.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 java.lang.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 defined in M2_HOME system env variables or null if never set.

Since:

2.6

getMavenOpts

private static java.lang.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 java.io.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 java.lang.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 java.util.List<java.lang.String> toList(java.lang.String src)

toList

static java.util.List<java.lang.String> toList(java.lang.String src,
                                               java.lang.String elementPrefix,
                                               java.lang.String elementSuffix)

toList

static <T> java.util.List<T> toList(T[] multiple)

toList

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

toRelative

public static java.lang.String toRelative(java.io.File basedir,
                                          java.lang.String absolutePath)

isNotEmpty

public static boolean isNotEmpty(java.util.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(java.util.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 java.net.URL getRedirectUrl(java.net.URL url,
                                             org.apache.maven.settings.Settings settings)
                                      throws java.io.IOException

Execute an Http request at the given URL, follows redirects, and returns the last redirect locations. For URLs that aren't http/https, this does nothing and simply returns the given URL unchanged.

Parameters:

url - URL.

settings - Maven settings.

Returns:

Last redirect location.

Throws:

java.io.IOException - if there was an error during the Http request.

isValidPackageList

protected static boolean isValidPackageList(java.net.URL url,
                                            org.apache.maven.settings.Settings settings,
                                            boolean validateContent)
                                     throws java.io.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:

java.io.IOException - if reading the resource fails.

Since:

2.8

See Also:

createHttpClient(org.apache.maven.settings.Settings, java.net.URL)

isValidPackageName

private static boolean isValidPackageName(java.lang.String str)

isValidClassName

private static boolean isValidClassName(java.lang.String str)

createHttpClient

private static org.apache.http.client.HttpClient createHttpClient(org.apache.maven.settings.Settings settings,
                                                                  java.net.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:

DEFAULT_TIMEOUT

equalsIgnoreCase

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

equals

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