Javadoc built with Java 11 does not include platform APIs
Description
Environment
is related to
Activity
Ian Young January 14, 2020 at 4:40 PM
Updated to Javadoc plugin 3.1.1 in commit 9d07f44329061e0f287b949a613eff237b9d8bce.
Declaring victory here; https://shibboleth.atlassian.net/browse/JPAR-157#icft=JPAR-157 is the follow-on but isn't tied to IdP V4.
Ian Young January 14, 2020 at 4:37 PM
New issue for the EE stuff: JPAR-157.
Ian Young January 14, 2020 at 4:12 PM
Looks like this one is going to run and run. The current situation seems to be that as of the latest (3.1.1) Javadoc plugin and most recent versions of Java, the Java SE APIs are working.
However, even with that version the Java EE APIs still cause the problem. I've adjusted that link (in commit 19ebd83f173aec942d50360d53d2f67f4bd784ed) to point to the EE 7 APIs, which is what we're using, but that doesn't change anything.
It looks like there is yet another outstanding issue on the plugin: https://issues.apache.org/jira/browse/MJAVADOC-615 "Workaround for bug JDK-8212233 does no longer work in 3.1.1 when using Java 12" the body of which claims failures in Java 12 but also in Java 11. This was reported in 2019-07, has been put in the pile for MJAVADOC 3.2.0, but no work done on it as of 2020-01-14.
I'm going to update the plugin to 3.1.1 and confirm that everything except the J2EE APIs are working, and then resolve this. I may create a new ticket for the J2EE-specific issue, but it's far less important than the other modules.
Ian Young October 24, 2019 at 2:27 PM
There is another version of the maven-javadoc-plugin (3.1.1) which has a couple of fixes which look like they might be relevant, e.g.:
MJAVADOC-539 "Upgrading plugin from 3.0.0 to 3.0.1 and 3.1.0 breaks certain external javadoc links"
We're also at 11.0.5 now so another couple of batches of back-ported fixes to Java 11 have happened.
Time to give upgrading to the latest shiny thing another try, in the hope that it will fix these issues.
Ian Young May 27, 2019 at 4:32 PM
Now that we're building with something other than Oracle's JDK 11.0.3, I looked at this again. Results were as above until I tried adding in the Java EE 5 API link again. That still causes the error even under Corretto 11.0.3.
Needs more investigation. It looks like the 3.1.0 maven-javadoc-plugin is viable, though, for everything else and there are related things I think it will address (e.g., https://shibboleth.atlassian.net/browse/JPAR-134#icft=JPAR-134).
There are a significant number of bugs in the
maven-javadoc-pluginand in the JDK'sjavadoctool. The lists of bugs evolve between versions and interact with each other in unpleasant ways.As things stand today, although per https://shibboleth.atlassian.net/browse/JPAR-122#icft=JPAR-122 it is possible with
maven-javadoc-plugin3.0.1 to avoid NPEs while building with Java 11 (as we'll need to do for the V11 product platform), it does not appear to be possible to fully populate links to either the Java EE API or to the platform API. The most common excursion from correct behaviour is a message to the effect that the referenced API has packages in the unnamed module (which is true for Java EE 5 and Java 8) and that this is not compatible with a modular build (which we're not doing).The relevant bugs seem to be MJAVADOC-555 and JDK-8212233, but there may be others. It is possible that
maven-javadoc-plugin3.1.0 will resolve this. When it comes out, at least, we should look at this again and see if we can thread our way between Scylla and Charybdis once more.