This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch MJAVADOC-650
in repository https://gitbox.apache.org/repos/asf/maven-javadoc-plugin.git
commit a4aafaba9b5f2e409fc04b74b19c81ad4583106f
Author: Evan Ward <evan.w...@nrl.navy.mil>
AuthorDate: Thu Sep 17 08:35:14 2020 -0400
[MJAVADOC-650] Add explainer for how java.home changed in Java 9
Closes #60
---
.../maven/plugins/javadoc/AbstractJavadocMojo.java | 39 +++++++++++++++++++---
1 file changed, 34 insertions(+), 5 deletions(-)
diff --git
a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java
b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java
index cb21c12..040e1ca 100644
--- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java
+++ b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java
@@ -135,6 +135,7 @@ import java.util.Properties;
import java.util.Set;
import java.util.StringTokenizer;
+import static org.apache.commons.lang3.SystemUtils.isJavaVersionAtLeast;
import static org.apache.maven.plugins.javadoc.JavadocUtil.toRelative;
import static org.apache.maven.plugins.javadoc.JavadocUtil.toList;
import static org.apache.maven.plugins.javadoc.JavadocUtil.isEmpty;
@@ -3780,13 +3781,41 @@ public abstract class AbstractJavadocMojo
return javadocExe.getAbsolutePath();
}
-
+ // CHECKSTYLE_OFF: LineLength
//
----------------------------------------------------------------------
// Try to find javadocExe from System.getProperty( "java.home" )
- // By default, System.getProperty( "java.home" ) = JRE_HOME and
JRE_HOME
- // should be in the JDK_HOME
+ // "java.home" is the "Installation directory for Java Runtime
+ // Environment (JRE)" used to run this code. I.e. it is the parent of
+ // the directory containing the `java` command used to start this
+ // application. It does not necessarily have any relation to the
+ // environment variable JAVA_HOME.
+ //
+ // In Java 8 and below the JRE is separate from the JDK. When
+ // installing the JDK to my-dir/ the javadoc command is installed in
+ // my-dir/bin/javadoc, the JRE is installed to my-dir/jre, and hence
+ // the java command is installed to my-dir/jre/bin/java. In this
+ // configuration "java.home" is mydir/jre/, threfore the relative path
+ // to the javadoc command is ../bin/javadoc.
+ //
+ // In Java 9 and above the JRE is no longer in a subdirectory of the
+ // JDK, i.e. the JDK and the JDK are merged. In this case the java
+ // command is installed to my-dir/bin/java along side the javadoc
+ // command. So the relative path from "java.home" to the javadoc
+ // command is bin/javadoc.
+ //
+ // References
+ //
+ // "System Properties" in "The Java Tutorials"
+ //
https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html
+ //
+ // "Changes to the Installed JDK/JRE Image" in "JDK 9 Migration Guide"
+ //
https://docs.oracle.com/javase/9/migrate/toc.htm?xd_co_f=122a7174-9132-4acd-b122-fac02f8c4fef#JSMIG-GUID-D867DCCC-CEB5-4AFA-9D11-9C62B7A3FAB1
+ //
+ // "JEP 220: Modular Run-Time Images"
+ // http://openjdk.java.net/jeps/220
//
----------------------------------------------------------------------
// For IBM's JDK 1.2
+ // CHECKSTYLE_ON: LineLength
if ( SystemUtils.IS_OS_AIX )
{
javadocExe =
@@ -3799,14 +3828,14 @@ public abstract class AbstractJavadocMojo
{
javadocExe = new File( SystemUtils.getJavaHome() + File.separator
+ "bin", javadocCommand );
}
- // On Java 9 the jre subdirectory was removed from the JDK
- else if ( org.apache.commons.lang3.SystemUtils.isJavaVersionAtLeast(
org.apache.commons.lang3.JavaVersion.JAVA_9 ) )
+ else if ( isJavaVersionAtLeast(
org.apache.commons.lang3.JavaVersion.JAVA_9 ) )
{
javadocExe =
new File( SystemUtils.getJavaHome() + File.separator + "bin",
javadocCommand );
}
else
{
+ // Java <= 8
javadocExe =
new File( SystemUtils.getJavaHome() + File.separator + ".." +
File.separator + "bin", javadocCommand );
}
