Package org.apache.maven.plugins.javadoc
Class AbstractJavadocMojo
- java.lang.Object
-
- org.apache.maven.plugin.AbstractMojo
-
- org.apache.maven.plugins.javadoc.AbstractJavadocMojo
-
- All Implemented Interfaces:
org.apache.maven.plugin.ContextEnabled
,org.apache.maven.plugin.Mojo
- Direct Known Subclasses:
JavadocJar
,JavadocReport
,ResourcesBundleMojo
public abstract class AbstractJavadocMojo extends org.apache.maven.plugin.AbstractMojo
Base class with majority of Javadoc functionalities.- Since:
- 2.0
- Version:
- $Id: AbstractJavadocMojo.java 1801354 2017-07-09 08:49:46Z rfscholte $
- Author:
- Brett Porter, Vincent Siveton
- See Also:
- The Java API Documentation Generator, 7
-
-
Field Summary
Fields Modifier and Type Field Description protected static java.lang.String
ARGFILE_FILE_NAME
Theargfile
file name in the output directory when calling:javadoc.exe(or .sh) @options @packages | @argfile | @files
protected static java.lang.String
DEBUG_JAVADOC_SCRIPT_NAME
The Javadoc script file name whendebug
parameter is on, i.e.static java.util.Properties
DEFAULT_JAVA_API_LINKS
The default Javadoc API urls according the Sun API Specifications: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 java.lang.String
FILES_FILE_NAME
Thefiles
file name in the output directory when calling:javadoc.exe(or .sh) @options @packages | @argfile | @files
static java.lang.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 java.util.ArrayList<java.lang.String>
links
Creates links to existing javadoc-generated documentation of external referenced classes.protected static java.lang.String
OPTIONS_FILE_NAME
Theoptions
file name in the output directory when calling:javadoc.exe(or .sh) @options @packages | @argfile | @files
protected java.io.File
outputDirectory
Specifies the destination directory where javadoc saves the generated HTML files.protected static java.lang.String
PACKAGES_FILE_NAME
Thepackages
file name in the output directory when calling:javadoc.exe(or .sh) @options @packages | @argfile | @files
protected org.apache.maven.project.MavenProject
project
The Maven Project Objectprotected org.apache.maven.execution.MavenSession
session
The current build session instance.protected boolean
skip
Specifies whether the Javadoc generation should be skipped.static java.lang.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.
-
Constructor Summary
Constructors Constructor Description AbstractJavadocMojo()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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(java.util.List<java.lang.String> files)
Method that indicates whether the javadoc can be generated or not.protected java.util.Collection<java.lang.String>
collect(java.util.Collection<java.util.Collection<java.lang.String>> sourcePaths)
protected SourceResolverConfig
configureDependencySourceResolution(SourceResolverConfig config)
Override this method to customize the configuration for resolving dependency sources.void
execute()
protected void
executeReport(java.util.Locale unusedLocale)
The package documentation details the Javadoc Options used by this Plugin.protected void
failOnError(java.lang.String prefix, java.lang.Exception e)
protected java.lang.String
getAttachmentClassifier()
Override this if you need to provide a bundle attachment classifier, as in the case of test javadocs.protected org.apache.maven.shared.artifact.filter.resolve.ScopeFilter
getDependencyScopeFilter()
protected java.util.Map<java.lang.String,java.util.Collection<java.lang.String>>
getDependencySourcePaths()
Resolve dependency sources so they can be included directly in the javadoc process.protected java.lang.String
getDoclint()
protected java.lang.String
getDoctitle()
protected java.util.List<java.lang.String>
getExecutionProjectSourceRoots(org.apache.maven.project.MavenProject p)
protected java.util.List<java.lang.String>
getFiles(java.util.Collection<java.lang.String> sourcePaths)
Method to get the files on the specified source pathsprotected java.io.File
getJavadocDirectory()
protected java.io.File
getJavadocOptionsFile()
Construct the output file for the generated javadoc-options XML file, after creating the javadocOptionsDir if necessary.protected java.lang.String
getOutputDirectory()
protected java.io.File
getOverview()
protected org.apache.maven.project.MavenProject
getProject()
protected java.util.List<java.io.File>
getProjectBuildOutputDirs(org.apache.maven.project.MavenProject p)
protected java.util.List<java.lang.String>
getProjectSourceRoots(org.apache.maven.project.MavenProject p)
protected java.util.Map<java.lang.String,java.util.Collection<java.lang.String>>
getSourcePaths()
Method to get the source paths.protected org.apache.maven.toolchain.Toolchain
getToolchain()
protected java.lang.String
getWindowtitle()
protected boolean
isAggregator()
Indicates whether this goal is flagged with@aggregator
.protected boolean
isTest()
Indicates whether this goal generates documentation for theJava Test code
.protected boolean
isValidJavadocLink(java.lang.String link, boolean detecting)
protected void
logError(java.lang.String message, java.lang.Throwable t)
Logs an error with throwable content only if in debug.org.apache.maven.artifact.Artifact
resolveDependency(org.apache.maven.model.Dependency dependency)
protected void
verifyRemovedParameter(java.lang.String paramName)
-
-
-
Field Detail
-
JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER
public static final java.lang.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 java.lang.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
-
DEFAULT_JAVA_API_LINKS
public static final java.util.Properties DEFAULT_JAVA_API_LINKS
The default Javadoc API urls according the Sun API Specifications:<javaApiLinks> <property> <name>api_1.3</name> <value>http://docs.oracle.com/javase/1.3/docs/api/</value> </property> <property> <name>api_1.4</name> <value>http://docs.oracle.com/javase/1.4.2/docs/api/</value> </property> <property> <name>api_1.5</name> <value>http://docs.oracle.com/javase/1.5.0/docs/api/</value> </property> <property> <name>api_1.6</name> <value>http://docs.oracle.com/javase/6/docs/api/</value> </property> <property> <name>api_1.7</name> <value>http://docs.oracle.com/javase/7/docs/api/</value> </property> <property> <name>api_1.8</name> <value>http://docs.oracle.com/javase/8/docs/api/</value> </property> </javaApiLinks>
- Since:
- 2.6
-
DEBUG_JAVADOC_SCRIPT_NAME
protected static final java.lang.String DEBUG_JAVADOC_SCRIPT_NAME
The Javadoc script file name whendebug
parameter is on, i.e. javadoc.bat or javadoc.sh
-
OPTIONS_FILE_NAME
protected static final java.lang.String OPTIONS_FILE_NAME
Theoptions
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 java.lang.String PACKAGES_FILE_NAME
Thepackages
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 java.lang.String ARGFILE_FILE_NAME
Theargfile
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 java.lang.String FILES_FILE_NAME
Thefiles
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 org.apache.maven.execution.MavenSession session
The current build session instance. This is used for toolchain manager API calls.
-
project
@Parameter(defaultValue="${project}", readonly=true, required=true) protected org.apache.maven.project.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 java.util.ArrayList<java.lang.String> links
Creates links to existing javadoc-generated documentation of external referenced classes.
Notes:- only used if
isOffline
is set tofalse
. - all given links should have a fetchable
/package-list
file. For instance:<links> <link>http://docs.oracle.com/javase/1.4.2/docs/api</link> <links>
will be used becausehttp://docs.oracle.com/javase/1.4.2/docs/api/package-list
exists. - if
detectLinks
is defined, the links between the project dependencies are automatically added. - if
detectJavaApiLink
is defined, a Java API link, based on the Java version of the project's sources, will be added automatically.
- See Also:
detectLinks
,detectJavaApiLink
- only used if
-
outputDirectory
@Parameter(property="destDir", alias="destDir", defaultValue="${project.build.directory}/apidocs", required=true) protected java.io.File outputDirectory
Specifies the destination directory where javadoc saves the generated HTML files.- See Also:
- d option
-
-
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 theJava Test code
.- Returns:
true
if the goal generates Test Javadocs,false
otherwise.
-
getOutputDirectory
protected java.lang.String getOutputDirectory()
- Returns:
- the output directory
-
getProject
protected org.apache.maven.project.MavenProject getProject()
-
getProjectBuildOutputDirs
protected java.util.List<java.io.File> getProjectBuildOutputDirs(org.apache.maven.project.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.
-
getProjectSourceRoots
protected java.util.List<java.lang.String> getProjectSourceRoots(org.apache.maven.project.MavenProject p)
- Parameters:
p
- not null maven project- Returns:
- the list of source paths for the given project
-
getExecutionProjectSourceRoots
protected java.util.List<java.lang.String> getExecutionProjectSourceRoots(org.apache.maven.project.MavenProject p)
- Parameters:
p
- not null maven project- Returns:
- the list of source paths for the execution project of the given project
-
getJavadocDirectory
protected java.io.File getJavadocDirectory()
- Returns:
- the current javadoc directory
-
getDoclint
protected java.lang.String getDoclint()
- Returns:
- the doclint specific checks configuration
-
getDoctitle
protected java.lang.String getDoctitle()
- Returns:
- the title to be placed near the top of the overview summary file
-
getOverview
protected java.io.File getOverview()
- Returns:
- the overview documentation file from the user parameter or from the
javadocdirectory
-
getWindowtitle
protected java.lang.String getWindowtitle()
- Returns:
- the title to be placed in the HTML title tag
-
execute
public void execute() throws org.apache.maven.plugin.MojoExecutionException, org.apache.maven.plugin.MojoFailureException
- Throws:
org.apache.maven.plugin.MojoExecutionException
org.apache.maven.plugin.MojoFailureException
-
verifyRemovedParameter
protected final void verifyRemovedParameter(java.lang.String paramName)
-
executeReport
protected void executeReport(java.util.Locale unusedLocale) throws org.apache.maven.reporting.MavenReportException
The package documentation details the Javadoc Options used by this Plugin.- Parameters:
unusedLocale
- the wanted locale (actually unused).- Throws:
org.apache.maven.reporting.MavenReportException
- if any
-
collect
protected final java.util.Collection<java.lang.String> collect(java.util.Collection<java.util.Collection<java.lang.String>> sourcePaths)
-
getFiles
protected java.util.List<java.lang.String> getFiles(java.util.Collection<java.lang.String> sourcePaths) throws org.apache.maven.reporting.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:
org.apache.maven.reporting.MavenReportException
-MavenReportException
-
getSourcePaths
protected java.util.Map<java.lang.String,java.util.Collection<java.lang.String>> getSourcePaths() throws org.apache.maven.reporting.MavenReportException
Method to get the source paths. If no source path is specified in the parameter, the compile source roots of the project will be used.- Returns:
- a Collection of the project absolute source paths as
String
- Throws:
org.apache.maven.reporting.MavenReportException
-MavenReportException
- 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 java.util.Map<java.lang.String,java.util.Collection<java.lang.String>> getDependencySourcePaths() throws org.apache.maven.reporting.MavenReportException
Resolve dependency sources so they can be included directly in the javadoc process. To customize this, overrideconfigureDependencySourceResolution(SourceResolverConfig)
.- Returns:
- List of source paths.
- Throws:
org.apache.maven.reporting.MavenReportException
-MavenReportException
-
canGenerateReport
protected boolean canGenerateReport(java.util.List<java.lang.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 org.apache.maven.artifact.Artifact resolveDependency(org.apache.maven.model.Dependency dependency) throws org.apache.maven.reporting.MavenReportException
- Parameters:
dependency
-Dependency
- Returns:
Artifact
- Throws:
org.apache.maven.reporting.MavenReportException
- when artifact could not be resolved
-
getToolchain
protected final org.apache.maven.toolchain.Toolchain getToolchain()
-
isValidJavadocLink
protected boolean isValidJavadocLink(java.lang.String link, boolean detecting)
- Parameters:
link
- not nulldetecting
-true
if the link is generated bydetectLinks
, orfalse
otherwise- Returns:
true
if the link has a/package-list
,false
otherwise.- Since:
- 2.6
- See Also:
- package-list spec
-
getJavadocOptionsFile
protected final java.io.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 java.io.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:
java.io.IOException
-IOException
- Since:
- 2.7
-
getAttachmentClassifier
protected java.lang.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(java.lang.String message, java.lang.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(java.lang.String prefix, java.lang.Exception e) throws org.apache.maven.plugin.MojoExecutionException
- Parameters:
prefix
- The prefix of the exception.e
- The exception.- Throws:
org.apache.maven.plugin.MojoExecutionException
-MojoExecutionException
-
-