org.apache.maven.plugins.javadoc

Class AbstractJavadocMojo

java.lang.Object

org.apache.maven.plugin.AbstractMojo

org.apache.maven.plugins.javadoc.AbstractJavadocMojo

All Implemented Interfaces:

ContextEnabled, Mojo

Direct Known Subclasses:

JavadocJar, JavadocReport, ResourcesBundleMojo

public abstract class AbstractJavadocMojo
extends AbstractMojo

Base class with majority of Javadoc functionalities.

Since:

2.0

Author:

Brett Porter, Vincent Siveton

See Also:

The Java API Documentation Generator, 7

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	ARGFILE_FILE_NAME The argfile file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files
protected static String	DEBUG_JAVADOC_SCRIPT_NAME The Javadoc script file name when debug parameter is on, i.e.
protected boolean	failOnError Specifies if the build will fail if there are errors during javadoc execution or not.
protected boolean	failOnWarnings Specifies if the build will fail if there are warning during javadoc execution or not.
protected static String	FILES_FILE_NAME The files file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files
static String	JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER Classifier used in the name of the javadoc-options XML file, and in the resources bundle artifact that gets attached to the project.
protected ArrayList<String>	links Creates links to existing javadoc-generated documentation of external referenced classes.
protected static String	OPTIONS_FILE_NAME The options file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files
protected File	outputDirectory Specifies the destination directory where javadoc saves the generated HTML files.
protected String	outputTimestamp Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).
protected static String	PACKAGES_FILE_NAME The packages file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files
protected MavenProject	project The Maven Project Object
protected MavenSession	session The current build session instance.
protected boolean	skip Specifies whether the Javadoc generation should be skipped.
static String	TEST_JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER Classifier used in the name of the javadoc-options XML file, and in the resources bundle artifact that gets attached to the project.
protected boolean	useStandardDocletOptions Specifies to use the options provided by the Standard Doclet for a custom doclet.

Fields inherited from interface org.apache.maven.plugin.Mojo

ROLE

Constructor Summary

Constructors

Constructor and Description
AbstractJavadocMojo()

Method Summary

Modifier and Type	Method and Description
protected JavadocOptions	buildJavadocOptions() Generate a javadoc-options XML file, for either bundling with a javadoc-resources artifact OR supplying to a distro module in a includeDependencySources configuration, so the javadoc options from this execution can be reconstructed and merged in the distro build.
protected boolean	canGenerateReport(Map<Path,Collection<String>> files) Method that indicates whether the javadoc can be generated or not.
protected SourceResolverConfig	configureDependencySourceResolution(SourceResolverConfig config) Override this method to customize the configuration for resolving dependency sources.
void	execute()
protected void	executeReport(Locale unusedLocale) The package documentation details the Javadoc Options used by this Plugin.
protected void	failOnError(String prefix, Exception e)
protected String	getAttachmentClassifier() Override this if you need to provide a bundle attachment classifier, as in the case of test javadocs.
protected File	getClassesFile(MavenProject project) Either returns the attached artifact file or outputDirectory
protected OfflineLink	getDefaultJavadocApiLink()
protected org.apache.maven.shared.artifact.filter.resolve.ScopeFilter	getDependencyScopeFilter()
protected Collection<JavadocModule>	getDependencySourcePaths() Resolve dependency sources so they can be included directly in the javadoc process.
protected String	getDoclint()
protected String	getDoctitle()
protected List<String>	getExecutionProjectSourceRoots(MavenProject p)
protected Map<Path,Collection<String>>	getFiles(Collection<Path> sourcePaths) Method to get the files on the specified source paths
protected File	getJavadocDirectory()
protected File	getJavadocOptionsFile() Construct the output file for the generated javadoc-options XML file, after creating the javadocOptionsDir if necessary.
protected String	getOutputDirectory()
protected File	getOverview()
protected MavenProject	getProject()
protected List<File>	getProjectBuildOutputDirs(MavenProject p)
protected List<String>	getProjectSourceRoots(MavenProject p)
protected Collection<JavadocModule>	getSourcePaths() Method to get the source paths per reactorProject.
protected Toolchain	getToolchain()
protected String	getWindowtitle()
protected boolean	isAggregator() Indicates whether this goal is flagged with @aggregator.
protected boolean	isSkippedJavadoc(MavenProject mavenProject)
protected boolean	isSkippedModule(MavenProject mavenProject)
protected boolean	isTest() Indicates whether this goal generates documentation for the Java Test code.
protected boolean	isValidJavadocLink(String link, boolean detecting)
protected void	logError(String message, Throwable t) Logs an error with throwable content only if in debug.
Artifact	resolveDependency(Dependency dependency)
protected void	verifyRemovedParameter(String paramName)

Methods inherited from class org.apache.maven.plugin.AbstractMojo

getLog, getPluginContext, setLog, setPluginContext

Methods inherited from class java.lang.Object

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

Field Detail

JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER

public static final String JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER

Classifier used in the name of the javadoc-options XML file, and in the resources bundle artifact that gets attached to the project. This one is used for non-test javadocs.

Since:

2.7

See Also:

TEST_JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER, Constant Field Values

TEST_JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER

public static final String TEST_JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER

Classifier used in the name of the javadoc-options XML file, and in the resources bundle artifact that gets attached to the project. This one is used for test-javadocs.

Since:

2.7

See Also:

JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER, Constant Field Values

DEBUG_JAVADOC_SCRIPT_NAME

protected static final String DEBUG_JAVADOC_SCRIPT_NAME

The Javadoc script file name when debug parameter is on, i.e. javadoc.bat or javadoc.sh

OPTIONS_FILE_NAME

protected static final String OPTIONS_FILE_NAME

The options file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files

See Also:

Constant Field Values

PACKAGES_FILE_NAME

protected static final String PACKAGES_FILE_NAME

The packages file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files

See Also:

Constant Field Values

ARGFILE_FILE_NAME

protected static final String ARGFILE_FILE_NAME

The argfile file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files

See Also:

Constant Field Values

FILES_FILE_NAME

protected static final String FILES_FILE_NAME

The files file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files

See Also:

Constant Field Values

session

@Parameter(defaultValue="${session}",
           readonly=true,
           required=true)
protected MavenSession session

The current build session instance. This is used for toolchain manager API calls.

project

@Parameter(defaultValue="${project}",
           readonly=true,
           required=true)
protected MavenProject project

The Maven Project Object

skip

@Parameter(property="maven.javadoc.skip",
           defaultValue="false")
protected boolean skip

Specifies whether the Javadoc generation should be skipped.

Since:

2.5

failOnError

@Parameter(property="maven.javadoc.failOnError",
           defaultValue="true")
protected boolean failOnError

Specifies if the build will fail if there are errors during javadoc execution or not.

Since:

2.5

failOnWarnings

@Parameter(property="maven.javadoc.failOnWarnings",
           defaultValue="false")
protected boolean failOnWarnings

Specifies if the build will fail if there are warning during javadoc execution or not.

Since:

3.0.1

useStandardDocletOptions

@Parameter(property="useStandardDocletOptions",
           defaultValue="true")
protected boolean useStandardDocletOptions

Specifies to use the options provided by the Standard Doclet for a custom doclet.
Example:

 <docletArtifacts>
   <docletArtifact>
     <groupId>com.sun.tools.doclets</groupId>
     <artifactId>doccheck</artifactId>
     <version>1.2b2</version>
   </docletArtifact>
 </docletArtifacts>
 <useStandardDocletOptions>true</useStandardDocletOptions>
 

Since:

2.5

links

@Parameter(property="links")
protected ArrayList<String> links

Creates links to existing javadoc-generated documentation of external referenced classes.
Notes:

1. only used if isOffline is set to false.
2. all given links should have a fetchable /package-list file. For instance:

    <links>
      <link>https://docs.oracle.com/javase/1.4.2/docs/api</link>
    <links>
    

   will be used because https://docs.oracle.com/javase/1.4.2/docs/api/package-list exists.
3. if detectLinks is defined, the links between the project dependencies are automatically added.
4. if detectJavaApiLink is defined, a Java API link, based on the Java version of the project's sources, will be added automatically.

See link.

See Also:

detectLinks, detectJavaApiLink, dependencyLinks

outputDirectory

@Parameter(property="destDir",
           alias="destDir",
           defaultValue="${project.build.directory}/apidocs",
           required=true)
protected File outputDirectory

Specifies the destination directory where javadoc saves the generated HTML files.

See Also:

javadoc d

outputTimestamp

@Parameter(defaultValue="${project.build.outputTimestamp}")
protected String outputTimestamp

Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).

Since:

3.2.0

Constructor Detail

AbstractJavadocMojo

public AbstractJavadocMojo()

Method Detail

isAggregator

protected boolean isAggregator()

Indicates whether this goal is flagged with @aggregator.

Returns:

true if the goal is designed as an aggregator, false otherwise.

See Also:

AggregatorJavadocReport, AggregatorTestJavadocReport

isTest

protected boolean isTest()

Indicates whether this goal generates documentation for the Java Test code.

Returns:

true if the goal generates Test Javadocs, false otherwise.

getOutputDirectory

protected String getOutputDirectory()

Returns:

the output directory

getProject

protected MavenProject getProject()

getProjectBuildOutputDirs

protected List<File> getProjectBuildOutputDirs(MavenProject p)

Parameters:

p - not null maven project

Returns:

the list of directories where compiled classes are placed for the given project. These dirs are added in the javadoc classpath.

getClassesFile

protected File getClassesFile(MavenProject project)

Either returns the attached artifact file or outputDirectory

Parameters:

project -

Returns:

getProjectSourceRoots

protected List<String> getProjectSourceRoots(MavenProject p)

Parameters:

p - not null maven project

Returns:

the list of source paths for the given project

getExecutionProjectSourceRoots

protected List<String> getExecutionProjectSourceRoots(MavenProject p)

Parameters:

p - not null maven project

Returns:

the list of source paths for the execution project of the given project

getJavadocDirectory

protected File getJavadocDirectory()

Returns:

the current javadoc directory

getDoclint

protected String getDoclint()

Returns:

the doclint specific checks configuration

getDoctitle

protected String getDoctitle()

Returns:

the title to be placed near the top of the overview summary file

getOverview

protected File getOverview()

Returns:

the overview documentation file from the user parameter or from the javadocdirectory

getWindowtitle

protected String getWindowtitle()

Returns:

the title to be placed in the HTML title tag

execute

public void execute()
             throws MojoExecutionException,
                    MojoFailureException

Throws:

MojoExecutionException

MojoFailureException

verifyRemovedParameter

protected final void verifyRemovedParameter(String paramName)

executeReport

protected void executeReport(Locale unusedLocale)
                      throws MavenReportException

The package documentation details the Javadoc Options used by this Plugin.

Parameters:

unusedLocale - the wanted locale (actually unused).

Throws:

MavenReportException - if any

getFiles

protected Map<Path,Collection<String>> getFiles(Collection<Path> sourcePaths)
                                         throws MavenReportException

Method to get the files on the specified source paths

Parameters:

sourcePaths - a Collection that contains the paths to the source files

Returns:

a List that contains the specific path for every source file

Throws:

MavenReportException - MavenReportException issue while generating report

getSourcePaths

protected Collection<JavadocModule> getSourcePaths()
                                            throws MavenReportException

Method to get the source paths per reactorProject. If no source path is specified in the parameter, the compile source roots of the project will be used.

Returns:

a Map of the project absolute source paths per projects key (G:A)

Throws:

MavenReportException - MavenReportException issue while generating report

See Also:

JavadocUtil.pruneDirs(MavenProject, Collection)

configureDependencySourceResolution

protected SourceResolverConfig configureDependencySourceResolution(SourceResolverConfig config)

Override this method to customize the configuration for resolving dependency sources. The default behavior enables the resolution of -sources jar files.

Parameters:

config - SourceResolverConfig

Returns:

SourceResolverConfig

getDependencySourcePaths

protected final Collection<JavadocModule> getDependencySourcePaths()
                                                            throws MavenReportException

Resolve dependency sources so they can be included directly in the javadoc process. To customize this, override configureDependencySourceResolution(SourceResolverConfig).

Returns:

List of source paths.

Throws:

MavenReportException - MavenReportException

canGenerateReport

protected boolean canGenerateReport(Map<Path,Collection<String>> files)

Method that indicates whether the javadoc can be generated or not. If the project does not contain any source files and no subpackages are specified, the plugin will terminate.

Parameters:

files - the project files

Returns:

a boolean that indicates whether javadoc report can be generated or not

getDependencyScopeFilter

protected org.apache.maven.shared.artifact.filter.resolve.ScopeFilter getDependencyScopeFilter()

resolveDependency

public Artifact resolveDependency(Dependency dependency)
                           throws MavenReportException

Parameters:

dependency - Dependency

Returns:

Artifact

Throws:

MavenReportException - when artifact could not be resolved

getToolchain

protected final Toolchain getToolchain()

getDefaultJavadocApiLink

protected final OfflineLink getDefaultJavadocApiLink()

Returns:

if detectJavaApiLink, the Java API link based on the javaApiLinks properties and the value of the source parameter in the org.apache.maven.plugins:maven-compiler-plugin defined in ${project.build.plugins} or in ${project.build.pluginManagement}, or the javadocRuntimeVersion, or null if not defined.

Since:

2.6

See Also:

detectJavaApiLink, javaApiLinks, source parameter

isValidJavadocLink

protected boolean isValidJavadocLink(String link,
                                     boolean detecting)

Parameters:

link - not null

detecting - true if the link is generated by detectLinks, or false otherwise

Returns:

true if the link has a /package-list, false otherwise.

Since:

2.6

See Also:

package-list spec

getJavadocOptionsFile

protected final File getJavadocOptionsFile()

Construct the output file for the generated javadoc-options XML file, after creating the javadocOptionsDir if necessary. This method does NOT write to the file in question.

Returns:

The options File file.

Since:

2.7

buildJavadocOptions

protected final JavadocOptions buildJavadocOptions()
                                            throws IOException

Generate a javadoc-options XML file, for either bundling with a javadoc-resources artifact OR supplying to a distro module in a includeDependencySources configuration, so the javadoc options from this execution can be reconstructed and merged in the distro build.

Returns:

JavadocOptions

Throws:

IOException - IOException

Since:

2.7

getAttachmentClassifier

protected String getAttachmentClassifier()

Override this if you need to provide a bundle attachment classifier, as in the case of test javadocs.

Returns:

The attachment classifier.

logError

protected void logError(String message,
                        Throwable t)

Logs an error with throwable content only if in debug.

Parameters:

message - The message which should be announced.

t - The throwable part of the message.

failOnError

protected void failOnError(String prefix,
                           Exception e)
                    throws MojoExecutionException

Parameters:

prefix - The prefix of the exception.

e - The exception.

Throws:

MojoExecutionException - MojoExecutionException issue while generating report

isSkippedModule

protected boolean isSkippedModule(MavenProject mavenProject)

Returns:

true if the module need to be skipped from aggregate generation

isSkippedJavadoc

protected boolean isSkippedJavadoc(MavenProject mavenProject)

Returns:

true if the pom configuration skip javadoc generation for the project