org.apache.maven.plugin.javadoc
Class JavadocUtil

java.lang.Object
  extended by org.apache.maven.plugin.javadoc.JavadocUtil

public class JavadocUtil
extends java.lang.Object

Set of utilities methods for Javadoc.

Since:
2.4
Version:
$Id: JavadocUtil.html 829394 2012-08-19 17:31:42Z hboutemy $
Author:
Vincent Siveton

Field Summary
static int DEFAULT_TIMEOUT
          The default timeout used when fetching url, i.e. 2000.
protected static java.lang.String ERROR_INIT_VM
          Error message when VM could not be started using invoker.
 
Constructor Summary
JavadocUtil()
           
 
Method Summary
protected static void addFilesFromSource(java.util.List files, java.io.File sourceDirectory, 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)
          Deprecated. since 2.5, using copyJavadocResources(File, File, String) instead of.
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.
protected static void fetchURL(org.apache.maven.settings.Settings settings, java.net.URL url)
          Fetch an URL
protected static java.util.List getCompileArtifacts(java.util.Set artifacts)
          Deprecated. since 2.5, using getCompileArtifacts(Set, boolean) instead of.
protected static java.util.List getCompileArtifacts(java.util.Set artifacts, boolean withTestScope)
          Copy from MavenProject.getCompileArtifacts()
protected static java.util.List getExcludedNames(java.util.List 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 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 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 float getJavadocVersion(java.io.File javadocExe)
          Call the Javadoc tool and parse its output to find its version, i.e.: javadoc.exe(or .sh) -J-version
protected static java.util.List 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.
protected static void invokeMaven(org.apache.maven.plugin.logging.Log log, java.io.File localRepositoryDir, java.io.File projectFile, java.util.List 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.
protected static java.lang.String parseJavadocMemory(java.lang.String memory)
          Parse a memory string which be used in the JVM arguments -Xms or -Xmx.
protected static float parseJavadocVersion(java.lang.String output)
          Parse the output for 'javadoc -J-version' and return the javadoc version recognized.
protected static java.util.List pruneDirs(org.apache.maven.project.MavenProject project, java.util.List dirs)
          Method that removes the invalid directories in the specified directories.
protected static java.util.List pruneFiles(java.util.List 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.
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.
protected static java.lang.String unifyPathSeparator(java.lang.String path)
          Unify the given path with the current System path separator, to be plateform 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

protected static java.util.List pruneDirs(org.apache.maven.project.MavenProject project,
                                          java.util.List 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 list of String directories path that will be validated.
Returns:
a List of valid String directories absolute paths.

pruneFiles

protected static java.util.List pruneFiles(java.util.List 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.

getExcludedNames

protected static java.util.List getExcludedNames(java.util.List 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

getCompileArtifacts

protected static java.util.List getCompileArtifacts(java.util.Set artifacts)
Deprecated. since 2.5, using getCompileArtifacts(Set, boolean) instead of.

Copy from MavenProject.getCompileArtifacts()

Parameters:
artifacts - not null
Returns:
list of compile artifacts with compile scope

getCompileArtifacts

protected static java.util.List getCompileArtifacts(java.util.Set artifacts,
                                                    boolean withTestScope)
Copy from MavenProject.getCompileArtifacts()

Parameters:
artifacts - not null
withTestScope - flag to include or not the artifacts with test scope
Returns:
list of compile artifacts with or without test scope.

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)
                                    throws java.io.IOException
Deprecated. since 2.5, using copyJavadocResources(File, File, String) instead of.

Convenience method that copy all doc-files directories from javadocDir to the outputDirectory.

Parameters:
outputDirectory - the output directory
javadocDir - the javadoc directory
Throws:
java.io.IOException - if any

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 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 StringBuffer that contains the appended file names of the files to be included in the javadoc

getExcludedPackages

protected static java.util.List 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 files,
                                         java.io.File sourceDirectory,
                                         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

getJavadocVersion

protected static float getJavadocVersion(java.io.File javadocExe)
                                  throws java.io.IOException,
                                         org.codehaus.plexus.util.cli.CommandLineException,
                                         java.lang.IllegalArgumentException,
                                         java.util.regex.PatternSyntaxException
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:
parseJavadocVersion(String)

parseJavadocVersion

protected static float parseJavadocVersion(java.lang.String output)
                                    throws java.lang.IllegalArgumentException,
                                           java.util.regex.PatternSyntaxException
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.
Throws:
java.util.regex.PatternSyntaxException - if the output doesn't match with the output pattern (?s).*?([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.

fetchURL

protected static void fetchURL(org.apache.maven.settings.Settings settings,
                               java.net.URL url)
                        throws java.io.IOException
Fetch an URL

Parameters:
settings - the user settings used to fetch the url with an active proxy, if defined.
url - the url to fetch
Throws:
java.io.IOException - if any
See Also:
DEFAULT_TIMEOUT

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 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 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 (;), plateform 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 plateform 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 (;), plateform 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


Copyright © 2004-2009 The Apache Software Foundation. All Rights Reserved.