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

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 a URL in milliseconds.
`protected static java.lang.String`	`ERROR_INIT_VM`	Error message when VM could not be started using invoker.

Constructor Summary

Constructors
Constructor Description

JavadocUtil()

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`protected static void`	`copyJavadocResources(java.io.File outputDirectory, java.io.File javadocDir, java.lang.String excludedocfilessubdir)`	Convenience method that copies 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.
`protected static java.lang.String`	`extractJavadocVersion(java.lang.String output)`	Parse the output of 'javadoc -J-version' and return the javadoc version recognized.
`protected static java.util.Collection<java.lang.String>`	`getExcludedPackages(java.nio.file.Path sourceDirectory, java.util.Collection<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>`	`getExcludedPackages(java.util.Collection<java.nio.file.Path> sourcePaths, java.util.Collection<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>`	`getFilesFromSource(java.io.File sourceDirectory, java.util.List<java.lang.String> sourceFileIncludes, java.util.List<java.lang.String> sourceFileExcludes, java.util.Collection<java.lang.String> excludePackages)`	Convenience method that gets the files to be included in the javadoc.
`protected static java.util.List<java.lang.String>`	`getIncludedFiles(java.io.File sourceDirectory, java.lang.String[] fileList, java.util.Collection<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.:
`protected static java.net.URL`	`getRedirectUrl(java.net.URL url, org.apache.maven.settings.Settings settings)`	Execute an HTTP request to the given URL, follow redirects, and return the last redirect location.
`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 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, java.io.File globalSettingsFile, java.io.File userSettingsFile, java.io.File globalToolchainsFile, java.io.File userToolchainsFile)`	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.
`protected static boolean`	`isValidElementList(java.net.URL url, org.apache.maven.settings.Settings settings, boolean validateContent)`
`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.
`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.nio.file.Path>`	`pruneDirs(org.apache.maven.project.MavenProject project, java.util.Collection<java.lang.String> dirs)`	Method that removes the invalid classpath 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.
`static java.util.Collection<java.nio.file.Path>`	`prunePaths(org.apache.maven.project.MavenProject project, java.util.Collection<java.lang.String> paths, boolean includeFiles)`	Method that removes invalid classpath elements in the specified paths.
`protected static java.lang.String`	`quotedArgument(java.lang.String value)`	Convenience method to wrap a command line option-argument 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)`	Deprecated. use Files.readString(Path, Charset) in Java 11+ or new String(Files.readAllBytes(Path), Charset) in Java 8
`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 semicolon, to support Unix and Windows paths.
`static java.lang.String`	`toRelative(java.io.File basedir, java.lang.String absolutePath)`	Deprecated. use `Path.relativize(Path)` () instead
`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 a URL in milliseconds. The default value is 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

prunePaths
```
public static java.util.Collection<java.nio.file.Path> prunePaths(org.apache.maven.project.MavenProject project,
                                                                  java.util.Collection<java.lang.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 java.util.Collection<java.nio.file.Path> pruneDirs(org.apache.maven.project.MavenProject project,
                                                                 java.util.Collection<java.lang.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 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

getExcludedPackages
```
protected static java.util.List<java.lang.String> getExcludedPackages(java.util.Collection<java.nio.file.Path> sourcePaths,
                                                                      java.util.Collection<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

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 java.lang.String quotedArgument(java.lang.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 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 copies 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.util.Collection<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 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 java.util.Collection<java.lang.String> getExcludedPackages(java.nio.file.Path sourceDirectory,
                                                                            java.util.Collection<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:

the package names to be excluded

getFilesFromSource

protected static java.util.List<java.lang.String> getFilesFromSource(java.io.File sourceDirectory,
                                                                     java.util.List<java.lang.String> sourceFileIncludes,
                                                                     java.util.List<java.lang.String> sourceFileExcludes,
                                                                     java.util.Collection<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; 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(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)

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:: java.util.regex.PatternSyntaxException - if the output doesn't match the output pattern (?s).*?[^a-zA-Z]([0-9]+\\.?[0-9]*)(\\.([0-9]+))?.*.; java.lang.NullPointerException - if the output is null; java.lang.IllegalArgumentException - if the output is empty

parseJavadocMemory

protected static java.lang.String parseJavadocMemory(java.lang.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:: java.lang.NullPointerException - if the memory argument is null; java.lang.IllegalArgumentException - if the memory argument 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 check

Returns:

true if the given charset is supported by the JVM, false otherwise.

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,
                                  java.io.File globalSettingsFile,
                                  java.io.File userSettingsFile,
                                  java.io.File globalToolchainsFile,
                                  java.io.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 java.lang.String readFile(java.io.File javaFile,
                                           java.lang.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:

java.nio.charset.UnsupportedCharsetException - if the named charset is not supported

java.lang.NullPointerException - if the javaFile or encoding is null

Since:

2.6.1

splitPath
```
protected static java.lang.String[] splitPath(java.lang.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 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 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:

splitPath(String), File.pathSeparator

toRelative

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

Deprecated.

use Path.relativize(Path) () instead

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 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:

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)

isValidElementList

protected static boolean isValidElementList(java.net.URL url,
                                            org.apache.maven.settings.Settings settings,
                                            boolean validateContent)
                                     throws java.io.IOException

Throws:: java.io.IOException

Class JavadocUtil

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_TIMEOUT

ERROR_INIT_VM

Constructor Detail

JavadocUtil

Method Detail

prunePaths

pruneDirs

pruneFiles

shouldPruneFile

getExcludedPackages

quotedArgument

quotedPathArgument

copyJavadocResources

getIncludedFiles

getExcludedPackages

getFilesFromSource

getJavadocVersion

extractJavadocVersion

parseJavadocMemory

validateEncoding

getTagletClassNames

copyResource

invokeMaven

readFile

splitPath

unifyPathSeparator

toRelative

isNotEmpty

isEmpty

getRedirectUrl

isValidPackageList

isValidElementList