chore: fix javadoc with Java 9 and later

[hashar]

The javadoc path varies between Java 8 and 11, the Java 8 one having an
extra jre directory in the pathname:

Java 8:

$ /usr/lib/jvm/java-8-openjdk-amd64/bin/java
-XshowSettings:properties -version 2>&1|grep java.home
java.home = /usr/lib/jvm/java-8-openjdk-amd64/jre

Java 11

$ /usr/lib/jvm/java-11-openjdk-amd64/bin/java
-XshowSettings:properties -version 2>&1|grep java.home
java.home = /usr/lib/jvm/java-11-openjdk-amd64

Set javadocExecutable via Maven profiles which activate based on the JDK
version being used.

That fixes the build under Java 11 when JAVA_HOME is not set.

[CarstenWickner]

Hi @hashar,

Thanks for the effort of creating the PR.
Just two questions though:

1. Am I understanding correctly, that your fix works for Java 8 and Java 11, but not for any other Java version?
2. You say this fixes the JavaDoc generation under JDK 11 when the JAVA_HOME environment variable is not set. But that is used in the configuration now, isn't it?

<javadocExecutable>${java.home}/bin/javadoc</javadocExecutable>

Also: the GitHub Action that includes the JavaDoc generation is already running under JDK 11 and works fine.
What exactly is being fixed here then?

[hashar]

hi @CarstenWickner ,

My local environment is Java 11 and JAVA_HOME is not set. When running the javadoc goal it complains with:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.1.0:javadoc (default-cli) on project jsonschema-generator:
An error has occurred in Javadoc report generation: Unable to find javadoc command: The environment variable JAVA_HOME is not correctly set. -> [Help 1]

On GitHub I am guessing the action sets JAVA_HOME and there is no issue.

The reason for the error I encounter is, starting with Java 9, the binaries for the JDK and the JRK are now in the same directory and the Maven plugin does not take that in account. My change only refers to Java 8 and Java 11 which are the versions shipped by Debian, but the rule should have been for 8 and 9.

Regardless, looking at the plugin code, the issue was MJAVADOC-650
solved by apache/maven-javadoc-plugin@a4aafab which has a lengthy comment properly explaining the change introduced in Java 9.

So essentially my change can be dropped and repurposed to update the Maven javadoc plugin from 3.1.0 to 3.3.0 or later.

[hashar]

Reworked to update maven-javadoc-plugin from 3.1.0 to 3.4.0 which properly find the javadoc binary.

[CarstenWickner]

Thanks @hashar 😄

[hashar]

Thank you for doing the extra mile in code reviewing. Will let me update the maven-javadoc-plugin in some other code bases which used the maven profiles in order to find javadoc.