Maven Javadoc Plugin
  1. Maven Javadoc Plugin
  2. MJAVADOC-286

Version 2.7 in Maven Reactor may cause infinite recursion, symptoms similar to MJAVADOC-268

    Details

    • Type: Bug Bug
    • Status: Closed Closed
    • Priority: Critical Critical
    • Resolution: Fixed
    • Affects Version/s: 2.6
    • Fix Version/s: 2.8
    • Labels:
      None
    • Environment:
    • Patch Submitted:
      Yes
    • Number of attachments :
      1

      Description

      The getModulesLinks() method is unacceptably slow under certain conditions:
      1. project's url is defined
      2. one or more projects in reactor do not have any java sources and are not of "pom" packaging.
      For such projects the apidocs/ output folder is never created resulting in repeated invokation of a forked javadoc goal. It's more severe with high number of modules in reactor and high number of modules without any java sources.

      as an example checkout "hg clone https://hg.kenai.com/hg/forceten~src"

      The immediate problem is in the apidocsFile.exists() condition that re-triggers the forked invokation. The attached patch fixes that. However it looks suspicitions that the method is being called repeatedly for each module at all. Maybe the aborting condition at the start of the method body is wrong (I was not able to decypher that)

      workaround is to use 2.5 or not to specify the url in pom.xml or set the detectOfflineLinks parameter to "false".

        Issue Links

          Activity

          Hide
          Herve Boutemy added a comment -

          I have a question: why is a module trying to reference javadoc section of a module which it doesn't depend on?
          since the reactor should build modules in an order that preserves dependencies compilation order, IMHO, when a module hasn't been previously built (with its javadoc), it shows that there is no dependency on it, then it can safely be ignored
          did I miss something?

          Show
          Herve Boutemy added a comment - I have a question: why is a module trying to reference javadoc section of a module which it doesn't depend on? since the reactor should build modules in an order that preserves dependencies compilation order, IMHO, when a module hasn't been previously built (with its javadoc), it shows that there is no dependency on it, then it can safely be ignored did I miss something?
          Hide
          Herve Boutemy added a comment - - edited

          here is a patch that should help: it triggers offlinelinks only when the module is a dependency of the current module
          it works pretty well, but breaks MJAVADOC-181 IT: I don't understand why (the code change shouldn't impact this IT), and in fact, I think the IT is broken since library's pom.xml configure aggretae=true, then it's normal that sub-modules don't generate their own javadoc
          if someone could review and tell me if I'm mistaken...

          Show
          Herve Boutemy added a comment - - edited here is a patch that should help: it triggers offlinelinks only when the module is a dependency of the current module it works pretty well, but breaks MJAVADOC-181 IT: I don't understand why (the code change shouldn't impact this IT), and in fact, I think the IT is broken since library's pom.xml configure aggretae=true, then it's normal that sub-modules don't generate their own javadoc if someone could review and tell me if I'm mistaken...
          Hide
          Andy Schlaikjer added a comment -

          Here's a workaround I've found useful for generating cross-linked javadoc reports for all modules in a multi-module project while avoiding infinite recursion and/or Java out of heap memory errors:

          Environment:

          • Java 6
          • Maven 3.0.1
          • maven-javadoc-plugin:2.7
          • maven-site-plugin:3.0-beta-3

          Project layout:

          /                   # project root
          |- pom.xml          # parent pom
          |- module1/         #
          |  `- pom.xml       # inherits from /pom.xml
          `- module2/         #
          |  `- pom.xml       # inherits from /pom.xml
          `- childmulti/      # child multi-module
             |- pom.xml       # intermediate parent pom, inherits from /pom.xml
             |- module3/      #
             |  `- pom.xml    # inherits from /childmulti/pom.xml
             `- module4/      #
                `- pom.xml    # inherits from /childmulti/pom.xml
          

          Within /pom.xml:

          <project>
            ...
            <url>http://${host.name}/site/${site.name}/</url>
            ...
            <build>
              <pluginManagement>
                <plugins>
                  ...
                  <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>2.7</version>
                  </plugin>
                  ...
                  <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-site-plugin</artifactId>
                    <version>3.0-beta-3</version>
                    <configuration>
                      <reportPlugins>
                        <plugin>
                          <artifactId>maven-javadoc-plugin</artifactId>
                          <configuration>
                            <detectLinks>false</detectLinks>
                            <detectOfflineLinks>true</detectOfflineLinks>
                          </configuration>
                          <reports>
                            <report>javadoc</report>
                          </reports>
                        </plugin>
          
                        <!-- add more report plugins here -->
          
                      </reportPlugins>
                    </configuration>
                  </plugin>
                </plugins>
              </pluginManagement>
            </build>
            ...
          </project>
          

          Within /childmulti/pom.xml:

          <project>
            ...
            <url>http://${host.name}/site/${site.name}/childmulti/</url>
            ...
          </project>
          

          Notice that I've configured maven-javadoc-plugin to use the javadoc:javadoc report goal only, not the javadoc:aggregator report goal. In addition, the detectOfflineLinks parameter has been turned on.

          Using this config, if an aggregate site build is executed within the multi-module project root, the javadoc:javadoc report goal is executed independently for each module, but (due to behavior of detectOfflineLinks) each set of javadocs properly cross-references other modules' javadocs.

          One note: With this setup, the javadoc:javadoc report goal tries to fetch module poms from a repository during execution, instead of accessing the copies in your working directory, so all modules must be installed prior to execution of the site reactor build:

          $ cd /path/to/project/root/
          $ mvn install
          $ mvn site
          
          Show
          Andy Schlaikjer added a comment - Here's a workaround I've found useful for generating cross-linked javadoc reports for all modules in a multi-module project while avoiding infinite recursion and/or Java out of heap memory errors: Environment: Java 6 Maven 3.0.1 maven-javadoc-plugin:2.7 maven-site-plugin:3.0-beta-3 Project layout: / # project root |- pom.xml # parent pom |- module1/ # | `- pom.xml # inherits from /pom.xml `- module2/ # | `- pom.xml # inherits from /pom.xml `- childmulti/ # child multi-module |- pom.xml # intermediate parent pom, inherits from /pom.xml |- module3/ # | `- pom.xml # inherits from /childmulti/pom.xml `- module4/ # `- pom.xml # inherits from /childmulti/pom.xml Within /pom.xml : <project> ... <url>http://${host.name}/site/${site.name}/</url> ... <build> <pluginManagement> <plugins> ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.7</version> </plugin> ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <version>3.0-beta-3</version> <configuration> <reportPlugins> <plugin> <artifactId>maven-javadoc-plugin</artifactId> <configuration> <detectLinks>false</detectLinks> <detectOfflineLinks>true</detectOfflineLinks> </configuration> <reports> <report>javadoc</report> </reports> </plugin> <!-- add more report plugins here --> </reportPlugins> </configuration> </plugin> </plugins> </pluginManagement> </build> ... </project> Within /childmulti/pom.xml : <project> ... <url>http://${host.name}/site/${site.name}/childmulti/</url> ... </project> Notice that I've configured maven-javadoc-plugin to use the javadoc:javadoc report goal only, not the javadoc:aggregator report goal. In addition, the detectOfflineLinks parameter has been turned on. Using this config, if an aggregate site build is executed within the multi-module project root, the javadoc:javadoc report goal is executed independently for each module, but (due to behavior of detectOfflineLinks ) each set of javadocs properly cross-references other modules' javadocs. One note: With this setup, the javadoc:javadoc report goal tries to fetch module poms from a repository during execution, instead of accessing the copies in your working directory, so all modules must be installed prior to execution of the site reactor build: $ cd /path/to/project/root/ $ mvn install $ mvn site
          Hide
          Herve Boutemy added a comment -

          fixed in MJAVADOC-284

          Show
          Herve Boutemy added a comment - fixed in MJAVADOC-284

            People

            • Assignee:
              Vincent Siveton
              Reporter:
              Parag Mehta
            • Votes:
              2 Vote for this issue
              Watchers:
              8 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: