org.apache.maven.plugin.javadoc
Class AbstractJavadocMojo

java.lang.Object
  extended by org.apache.maven.plugin.AbstractMojo
      extended by org.apache.maven.plugin.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.html 829398 2012-08-19 17:38:59Z hboutemy $
Author:
Brett Porter, Vincent Siveton
See Also:
The Java API Documentation Generator, 1.4.2
Requires the dependencies in this specified scope:
compile

Field Summary
protected  boolean aggregate
          Deprecated. since 2.5. Use the goals javadoc:aggregate and javadoc:test-aggregate instead.
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. javadoc.bat or javadoc.sh
static Properties DEFAULT_JAVA_API_LINKS
          The default Javadoc API urls according the Sun API Specifications: <javaApiLinks> <property> <name>api_1.3</name> <value>http://download.oracle.com/javase/1.3/docs/api/</value> </property> <property> <name>api_1.4</name> <value>http://download.oracle.com/javase/1.4.2/docs/api/</value> </property> <property> <name>api_1.5</name> <value>http://download.oracle.com/javase/1.5.0/docs/api/</value> </property> <property> <name>api_1.6</name> <value>http://download.oracle.com/javase/6/docs/api/</value> </property> </javaApiLinks>
protected  boolean failOnError
          Specifies if the build will fail if there are errors 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 static String PACKAGES_FILE_NAME
          The packages 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 Object
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
AbstractJavadocMojo()
           
 
Method Summary
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(List<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.
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  List<org.apache.maven.artifact.Artifact> getCompileArtifacts(org.apache.maven.artifact.resolver.ArtifactResolutionResult result)
           
protected  List<String> getDependencySourcePaths()
          Resolve dependency sources so they can be included directly in the javadoc process.
protected  String getDoctitle()
           
protected  List<String> getExecutionProjectSourceRoots(org.apache.maven.project.MavenProject p)
           
protected  List<String> getFiles(List<String> 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  org.apache.maven.project.MavenProject getProject()
           
protected  List<org.apache.maven.artifact.Artifact> getProjectArtifacts(org.apache.maven.project.MavenProject p)
           
protected  List<String> getProjectBuildOutputDirs(org.apache.maven.project.MavenProject p)
           
protected  List<String> getProjectSourceRoots(org.apache.maven.project.MavenProject p)
           
protected  List<String> getSourcePaths()
          Method to get the source paths.
protected  String getWindowtitle()
           
protected  boolean isAggregator()
          Indicates whether this goal is flagged with @aggregator.
protected  void logError(String message, Throwable t)
          Logs an error with throwable content only if in debug.
 
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
 
Methods inherited from interface org.apache.maven.plugin.Mojo
execute
 

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

DEFAULT_JAVA_API_LINKS

public static final Properties DEFAULT_JAVA_API_LINKS
The default Javadoc API urls according the Sun API Specifications:
 <javaApiLinks>
   <property>
     <name>api_1.3</name>
     <value>http://download.oracle.com/javase/1.3/docs/api/</value>
   </property>
   <property>
     <name>api_1.4</name>
     <value>http://download.oracle.com/javase/1.4.2/docs/api/</value>
   </property>
   <property>
     <name>api_1.5</name>
     <value>http://download.oracle.com/javase/1.5.0/docs/api/</value>
   </property>
   <property>
     <name>api_1.6</name>
     <value>http://download.oracle.com/javase/6/docs/api/</value>
   </property>
 </javaApiLinks>
 

Since:
2.6

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

project

protected org.apache.maven.project.MavenProject project
The Maven Project Object

Is defined by:
expression:
${project}
Is readonly.
Is required.

aggregate

protected boolean aggregate
Deprecated. since 2.5. Use the goals javadoc:aggregate and javadoc:test-aggregate instead.
Whether to build an aggregated report at the root, or build individual reports.

Is defined by:
expression:
${aggregate}
default-value:
false

skip

protected boolean skip
Specifies whether the Javadoc generation should be skipped.

Since:
2.5
Is defined by:
expression:
${maven.javadoc.skip}
default-value:
false

failOnError

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

Since:
2.5
Is defined by:
expression:
${maven.javadoc.failOnError}
default-value:
true

useStandardDocletOptions

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
Is defined by:
expression:
${useStandardDocletOptions}
default-value:
true

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>http://download.oracle.com/javase/1.4.2/docs/api</link>
     <links>
     
    will be used because http://download.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
Is defined by:
expression:
${links}

outputDirectory

protected File outputDirectory
Specifies the destination directory where javadoc saves the generated HTML files.
See d.

Is defined by:
default-value:
${project.build.directory}/apidocs
expression:
${destDir}
alias:
destDir
Is required.
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

getOutputDirectory

protected String getOutputDirectory()
Returns:
the output directory

getProject

protected org.apache.maven.project.MavenProject getProject()

getProjectBuildOutputDirs

protected List<String> 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 List<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 List<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

getProjectArtifacts

protected List<org.apache.maven.artifact.Artifact> getProjectArtifacts(org.apache.maven.project.MavenProject p)
Parameters:
p - not null maven project
Returns:
the list of artifacts for the given project

getJavadocDirectory

protected File getJavadocDirectory()
Returns:
the current javadoc directory

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

executeReport

protected void executeReport(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

getFiles

protected List<String> getFiles(List<String> sourcePaths)
                         throws org.apache.maven.reporting.MavenReportException
Method to get the files on the specified source paths

Parameters:
sourcePaths - a List 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

getSourcePaths

protected List<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 List of the project absolute source paths as String
Throws:
org.apache.maven.reporting.MavenReportException
See Also:
JavadocUtil.pruneDirs(MavenProject, List)

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.


getDependencySourcePaths

protected final List<String> getDependencySourcePaths()
                                               throws org.apache.maven.reporting.MavenReportException
Resolve dependency sources so they can be included directly in the javadoc process. To customize this, override configureDependencySourceResolution(SourceResolverConfig).

Throws:
org.apache.maven.reporting.MavenReportException

canGenerateReport

protected boolean canGenerateReport(List<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

getCompileArtifacts

protected List<org.apache.maven.artifact.Artifact> getCompileArtifacts(org.apache.maven.artifact.resolver.ArtifactResolutionResult result)
Parameters:
result - not null
Returns:
the compile artifacts from the result
See Also:
JavadocUtil.getCompileArtifacts(Set, boolean)

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.

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.

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


logError

protected void logError(String message,
                        Throwable t)
Logs an error with throwable content only if in debug.

Parameters:
message -
t -

failOnError

protected void failOnError(String prefix,
                           Exception e)
                    throws org.apache.maven.plugin.MojoExecutionException
Throws:
org.apache.maven.plugin.MojoExecutionException


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