Package org.apache.maven.plugins.javadoc

Class AbstractJavadocMojo

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static java.lang.String ARGFILE_FILE_NAME
      The argfile 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 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 java.lang.String FILES_FILE_NAME
      The files 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 org.apache.maven.plugin.MojoExecution mojoExecution  
      protected static java.lang.String OPTIONS_FILE_NAME
      The options file name in the output directory when calling: javadoc.exe(or .sh) @options @packages | @argfile | @files
      protected java.io.File outputDirectory
      The shared output directory for the report where Javadoc saves the generated HTML files.
      protected java.lang.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 java.lang.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 java.util.List<org.apache.maven.project.MavenProject> reactorProjects
      The projects in the reactor for aggregation report.
      protected org.apache.maven.execution.MavenSession session
      The current build session instance.
      protected org.apache.maven.doxia.tools.SiteTool siteTool
      SiteTool.
      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.

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

        ROLE

    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractJavadocMojo​(org.apache.maven.doxia.tools.SiteTool siteTool, org.codehaus.plexus.archiver.manager.ArchiverManager archiverManager, ResourceResolver resourceResolver, org.eclipse.aether.RepositorySystem repoSystem, org.apache.maven.artifact.handler.manager.ArtifactHandlerManager artifactHandlerManager, org.apache.maven.project.ProjectBuilder mavenProjectBuilder, org.apache.maven.toolchain.ToolchainManager toolchainManager)  

    • Method Summary

      All Methods Instance Methods Abstract 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.Map<java.nio.file.Path,​java.util.Collection<java.lang.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 abstract void doExecute()  
      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 java.io.File getClassesFile​(org.apache.maven.project.MavenProject project)  
      protected OfflineLink getDefaultJavadocApiLink()  
      protected org.eclipse.aether.util.filter.ScopeDependencyFilter getDependencyScopeFilter()  
      protected java.util.Collection<JavadocModule> 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.Map<java.nio.file.Path,​java.util.Collection<java.lang.String>> getFiles​(java.util.Collection<java.nio.file.Path> sourcePaths)
      Method to get the files on the specified source paths
      protected 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 java.lang.String getPluginReportOutputDirectory()
      Method that returns the plugin report output directory where the generated Javadoc report will be put beneath getOutputDirectory()/org.apache.maven.reporting.AbstractMavenReport#getReportOutputDirectory().
      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.List<org.apache.maven.project.MavenProject> getReactorProjects()  
      protected java.util.Collection<JavadocModule> getSourcePaths()
      Method to get the source paths per reactorProject.
      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 isDetectOfflineLinks()  
      protected boolean isSkippedJavadoc​(org.apache.maven.project.MavenProject mavenProject)  
      protected boolean isSkippedModule​(org.apache.maven.project.MavenProject mavenProject)  
      protected boolean isTest()
      Indicates whether this goal generates documentation for the Java 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)  

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

      • DEBUG_JAVADOC_SCRIPT_NAME

        protected static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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

      • siteTool

        protected org.apache.maven.doxia.tools.SiteTool siteTool
        SiteTool.

      • 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

      • mojoExecution

        @Parameter(defaultValue="${mojoExecution}",
           readonly=true,
           required=true)
protected org.apache.maven.plugin.MojoExecution mojoExecution

      • reactorProjects

        @Parameter(defaultValue="${reactorProjects}",
           required=true,
           readonly=true)
protected java.util.List<org.apache.maven.project.MavenProject> reactorProjects
        The projects in the reactor for aggregation report.

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

        1. This option is ignored if the plugin is run in offline mode using the <offline> setting or by specifying -o, --offline or -Dmaven.javadoc.offline=true on the command line.
        2. All given links should have a fetchable /package-list or /element-list (since Java 10). For instance: 
           <links>
   <link>https://docs.oracle.com/en/java/javase/17/docs/api</link>
 </links>
          will be used because https://docs.oracle.com/en/java/javase/17/docs/api/element-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 Also:
        Doclet option link

      • outputDirectory

        @Parameter(defaultValue="${project.build.directory}/reports",
           required=true)
protected java.io.File outputDirectory
        The shared output directory for the report where Javadoc saves the generated HTML files. Note that this parameter is only evaluated if the goal is run directly from the command line. If the goal is run indirectly as part of a site generation, the shared output directory configured in the Maven Site Plugin is used instead.
        See Also:
        org.apache.maven.reporting.AbstractMavenReport#outputDirectory, Doclet option d

      • outputTimestamp

        @Parameter(defaultValue="${project.build.outputTimestamp}")
protected java.lang.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​(org.apache.maven.doxia.tools.SiteTool siteTool,
                           org.codehaus.plexus.archiver.manager.ArchiverManager archiverManager,
                           ResourceResolver resourceResolver,
                           org.eclipse.aether.RepositorySystem repoSystem,
                           org.apache.maven.artifact.handler.manager.ArtifactHandlerManager artifactHandlerManager,
                           org.apache.maven.project.ProjectBuilder mavenProjectBuilder,
                           org.apache.maven.toolchain.ToolchainManager toolchainManager)

    • Method Detail

      • 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 java.lang.String getOutputDirectory()

      • getPluginReportOutputDirectory

        protected java.lang.String getPluginReportOutputDirectory()
        Method that returns the plugin report output directory where the generated Javadoc report will be put beneath getOutputDirectory()/org.apache.maven.reporting.AbstractMavenReport#getReportOutputDirectory().
        Returns:
        a String that contains the target 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 to the javadoc classpath.

      • getClassesFile

        protected java.io.File getClassesFile​(org.apache.maven.project.MavenProject project)
        Parameters:
        project - the project in which to find a classes file
        Returns:
        null, the attached artifact file, or outputDirectory.

      • 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

      • doExecute

        protected abstract void doExecute()
                           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

      • getFiles

        protected java.util.Map<java.nio.file.Path,​java.util.Collection<java.lang.String>> getFiles​(java.util.Collection<java.nio.file.Path> 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 issue while generating report

      • getSourcePaths

        protected java.util.Collection<JavadocModule> getSourcePaths()
                                                      throws org.apache.maven.reporting.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:
        org.apache.maven.reporting.MavenReportException - MavenReportException issue while generating report
        See Also:
        JavadocUtil.pruneDirs(MavenProject, Collection)

      • getDependencySourcePaths

        protected final java.util.Collection<JavadocModule> 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).
        Returns:
        List of source paths.
        Throws:
        org.apache.maven.reporting.MavenReportException - MavenReportException

      • canGenerateReport

        protected boolean canGenerateReport​(java.util.Map<java.nio.file.Path,​java.util.Collection<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.eclipse.aether.util.filter.ScopeDependencyFilter 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()

      • isDetectOfflineLinks

        protected boolean isDetectOfflineLinks()

      • 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:
        source parameter

      • isValidJavadocLink

        protected boolean isValidJavadocLink​(java.lang.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 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

      • getReactorProjects

        protected java.util.List<org.apache.maven.project.MavenProject> getReactorProjects()

      • 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 issue while generating report

      • isSkippedModule

        protected boolean isSkippedModule​(org.apache.maven.project.MavenProject mavenProject)
        Parameters:
        mavenProject - the project that might be skipped
        Returns:
        true if the project needs to be skipped from aggregate generation

      • isSkippedJavadoc

        protected boolean isSkippedJavadoc​(org.apache.maven.project.MavenProject mavenProject)
        Parameters:
        mavenProject - the project that might be skipped
        Returns:
        true if the pom configuration skips javadoc generation for the project