Cleanup Javadocs in BootstrapCheck.java

This commit cleans up the formatting of some Javadocs in
BootstrapCheck.java, and corrects some docs that had become stale as the
bootstrap checks evolved.

core/src/main/java/org/elasticsearch/bootstrap/BootstrapCheck.java

@@ -48,11 +48,8 @@ import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 /**
- * We enforce limits once any network host is configured. In this case we assume the node is running in production
+ * We enforce bootstrap checks once a node has the transport protocol bound to a non-loopback interface. In this case we assume the node is
- * and all production limit checks must pass. This should be extended as we go to settings like:
+ * running in production and all bootstrap checks must pass.
- * - discovery.zen.ping.unicast.hosts is set if we use zen disco
- * - ensure we can write in all data directories
- * - fail if the default cluster.name is used, if this is setup on network a real clustername should be used?
  */
 final class BootstrapCheck {
 
@@ -60,8 +57,7 @@ final class BootstrapCheck {
     }
 
     /**
-     * checks the current limits against the snapshot or release build
+     * Executes the bootstrap checks if the node has the transport protocol bound to a non-loopback interface.
-     * checks
      *
      * @param settings              the current node settings
      * @param boundTransportAddress the node network bindings
@@ -74,15 +70,12 @@ final class BootstrapCheck {
     }
 
     /**
-     * executes the provided checks and fails the node if
+     * Executes the provided checks and fails the node if {@code enforceLimits} is {@code true}, otherwise logs warnings.
-     * enforceLimits is true, otherwise logs warnings
      *
-     * @param enforceLimits      true if the checks should be enforced or
+     * @param enforceLimits {@code true} if the checks should be enforced or otherwise warned
-     *                           otherwise warned
+     * @param checks        the checks to execute
-     * @param checks             the checks to execute
+     * @param nodeName      the node name to be used as a logging prefix
-     * @param nodeName           the node name to be used as a logging prefix
      */
-    // visible for testing
     static void check(
         final boolean enforceLimits,
         final List<Check> checks,
@@ -91,13 +84,11 @@ final class BootstrapCheck {
     }
 
     /**
-     * executes the provided checks and fails the node if
+     * Executes the provided checks and fails the node if {@code enforceLimits} is {@code true}, otherwise logs warnings.
-     * enforceLimits is true, otherwise logs warnings
      *
-     * @param enforceLimits      true if the checks should be enforced or
+     * @param enforceLimits {@code true} if the checks should be enforced or otherwise warned
-     *                           otherwise warned
+     * @param checks        the checks to execute
-     * @param checks             the checks to execute
+     * @param logger        the logger to
-     * @param logger             the logger to
      */
     static void check(
             final boolean enforceLimits,
@@ -140,12 +131,11 @@ final class BootstrapCheck {
     }
 
     /**
-     * Tests if the checks should be enforced
+     * Tests if the checks should be enforced.
      *
      * @param boundTransportAddress the node network bindings
-     * @return true if the checks should be enforced
+     * @return {@code true} if the checks should be enforced
      */
-    // visible for testing
     static boolean enforceLimits(BoundTransportAddress boundTransportAddress) {
         Predicate<TransportAddress> isLoopbackOrLinkLocalAddress = t -> t.address().getAddress().isLinkLocalAddress()
             || t.address().getAddress().isLoopbackAddress();
@@ -179,19 +169,19 @@ final class BootstrapCheck {
     }
 
     /**
-     * Encapsulates a limit check
+     * Encapsulates a bootstrap check.
      */
     interface Check {
 
         /**
-         * test if the node fails the check
+         * Test if the node fails the check.
          *
-         * @return true if the node failed the check
+         * @return {@code true} if the node failed the check
          */
         boolean check();
 
         /**
-         * the message for a failed check
+         * The error message for a failed check.
          *
          * @return the error message on check failure
          */
@@ -561,38 +551,58 @@ final class BootstrapCheck {
         public boolean check() {
             if ("Oracle Corporation".equals(jvmVendor()) && isJava8() && isG1GCEnabled()) {
                 final String jvmVersion = jvmVersion();
+                // HotSpot versions on Java 8 match this regular expression; note that this changes with Java 9 after JEP-223
                 final Pattern pattern = Pattern.compile("(\\d+)\\.(\\d+)-b\\d+");
                 final Matcher matcher = pattern.matcher(jvmVersion);
                 final boolean matches = matcher.matches();
                 assert matches : jvmVersion;
                 final int major = Integer.parseInt(matcher.group(1));
                 final int update = Integer.parseInt(matcher.group(2));
+                // HotSpot versions for Java 8 have major version 25, the bad versions are all versions prior to update 40
                 return major == 25 && update < 40;
             } else {
                 return false;
             }
         }
 
-        // visible for testing
+        /**
+         * Returns the JVM vendor as the G1GC check only applies to Oracle/OpenJDK JVMs that have "Oracle Corporation" as the vendor.
+         *
+         * @return the JVM vendor
+         */
         String jvmVendor() {
             return Constants.JVM_VENDOR;
         }
 
-        // visible for testing
+        /**
+         * Whether or not G1GC is enabled. This method should only be invoked when the JVM vendor is "Oracle Corporation".
+         *
+         * @return whether or not G1GC is enabled
+         */
         boolean isG1GCEnabled() {
             assert "Oracle Corporation".equals(jvmVendor());
             return JvmInfo.jvmInfo().useG1GC().equals("true");
         }
 
-        // visible for testing
+        /**
+         * The JVM version from the system property "java.vm.version". This method should only be invoked when the JVM vendor is
+         * "Oracle Corporation".
+         *
+         * @return the JVM version
+         */
         String jvmVersion() {
             assert "Oracle Corporation".equals(jvmVendor());
             return Constants.JVM_VERSION;
         }
 
-        // visible for tests
+        /**
+         * Whether or not the Java version is Java 8. This method should only be invoked when the JVM vendor is "Oracle Corporation".
+         *
+         * @return whether or not the Java version is Java 8.
+         */
         boolean isJava8() {
-            return Constants.JVM_SPEC_VERSION.equals("1.8");
+            assert "Oracle Corporation".equals(jvmVendor());
+            return JavaVersion.current().equals(JavaVersion.parse("1.8"));
         }
 
         @Override

core/src/test/java/org/elasticsearch/bootstrap/BootstrapCheckTests.java

@@ -592,12 +592,15 @@ public class BootstrapCheckTests extends ESTestCase {
         BootstrapCheck.check(true, Collections.singletonList(nonOracleCheck), "testG1GCCheck");
 
         final BootstrapCheck.G1GCCheck nonJava8Check = new BootstrapCheck.G1GCCheck() {
+
             @Override
             boolean isJava8() {
                 return false;
             }
+
         };
-        // if not java 8, nothing should happen
+
+        // if not Java 8, nothing should happen
         BootstrapCheck.check(true, Collections.singletonList(nonJava8Check), "testG1GCCheck");
     }