From 7e4cb2f09d1219c6ba7bfa77be831a7c7c9b055a Mon Sep 17 00:00:00 2001
From: Leo Korinth <lkorinth@openjdk.org>
Date: Thu, 9 Nov 2023 08:57:44 +0000
Subject: [PATCH] 8318962: Update ProcessTools javadoc with suggestions in
 8315097

Reviewed-by: rriggs
---
 .../jdk/test/lib/process/ProcessTools.java    | 94 +++++++++++++------
 1 file changed, 66 insertions(+), 28 deletions(-)

diff --git a/test/lib/jdk/test/lib/process/ProcessTools.java b/test/lib/jdk/test/lib/process/ProcessTools.java
index b4ee084d69f..db80a439f2b 100644
--- a/test/lib/jdk/test/lib/process/ProcessTools.java
+++ b/test/lib/jdk/test/lib/process/ProcessTools.java
@@ -492,12 +492,21 @@ public final class ProcessTools {
     }
 
     /**
-     * Create ProcessBuilder using the java launcher from the jdk to be tested.
-     * The default jvm options from jtreg, test.vm.opts and test.java.opts, are added.
-     * <p>
-     * The command line will be like:
-     * {test.jdk}/bin/java {test.vm.opts} {test.java.opts} cmds
-     * Create ProcessBuilder using the java launcher from the jdk to be tested.
+     * Create ProcessBuilder using the java launcher from the jdk to
+     * be tested. The default jvm options from jtreg, test.vm.opts and
+     * test.java.opts, are added.
+     *
+     * <p>Unless the "test.noclasspath" property is "true" the
+     * classpath property "java.class.path" is appended to the command
+     * line and the environment of the ProcessBuilder is modified to
+     * remove "CLASSPATH". If the property "test.thread.factory" is
+     * provided the command args are updated and appended to invoke
+     * ProcessTools main() and provide the name of the thread factory.
+     *
+     * <p>The "-Dtest.thread.factory" is appended to the arguments
+     * with the thread factory value. The remaining command args are
+     * scanned for unsupported options and are appended to the
+     * ProcessBuilder.
      *
      * @param command Arguments to pass to the java command.
      * @return The ProcessBuilder instance representing the java command.
@@ -507,12 +516,21 @@ public final class ProcessTools {
     }
 
     /**
-     * Create ProcessBuilder using the java launcher from the jdk to be tested.
-     * The default jvm options from jtreg, test.vm.opts and test.java.opts, are added.
-     * <p>
-     * The command line will be like:
-     * {test.jdk}/bin/java {test.vm.opts} {test.java.opts} cmds
-     * Create ProcessBuilder using the java launcher from the jdk to be tested.
+     * Create ProcessBuilder using the java launcher from the jdk to
+     * be tested. The default jvm options from jtreg, test.vm.opts and
+     * test.java.opts, are added.
+     *
+     * <p>Unless the "test.noclasspath" property is "true" the
+     * classpath property "java.class.path" is appended to the command
+     * line and the environment of the ProcessBuilder is modified to
+     * remove "CLASSPATH". If the property "test.thread.factory" is
+     * provided the command args are updated and appended to invoke
+     * ProcessTools main() and provide the name of the thread factory.
+     *
+     * <p>The "-Dtest.thread.factory" is appended to the arguments
+     * with the thread factory value. The remaining command args are
+     * scanned for unsupported options and are appended to the
+     * ProcessBuilder.
      *
      * @param command Arguments to pass to the java command.
      * @return The ProcessBuilder instance representing the java command.
@@ -536,6 +554,18 @@ public final class ProcessTools {
      * it in combination with <b>@requires vm.flagless</b> JTREG
      * anotation as to not waste energy and test resources.
      *
+     * <p>Unless the "test.noclasspath" property is "true" the
+     * classpath property "java.class.path" is appended to the command
+     * line and the environment of the ProcessBuilder is modified to
+     * remove "CLASSPATH". If the property "test.thread.factory" is
+     * provided the command args are updated and appended to invoke
+     * ProcessTools main() and provide the name of the thread factory.
+     *
+     * <p>The "-Dtest.thread.factory" is appended to the arguments
+     * with the thread factory value. The remaining command args are
+     * scanned for unsupported options and are appended to the
+     * ProcessBuilder.
+     *
      * @param command Arguments to pass to the java command.
      * @return The ProcessBuilder instance representing the java command.
      */
@@ -558,6 +588,18 @@ public final class ProcessTools {
      * it in combination with <b>@requires vm.flagless</b> JTREG
      * anotation as to not waste energy and test resources.
      *
+     * <p>Unless the "test.noclasspath" property is "true" the
+     * classpath property "java.class.path" is appended to the command
+     * line and the environment of the ProcessBuilder is modified to
+     * remove "CLASSPATH". If the property "test.thread.factory" is
+     * provided the command args are updated and appended to invoke
+     * ProcessTools main() and provide the name of the thread factory.
+     *
+     * <p>The "-Dtest.thread.factory" is appended to the arguments
+     * with the thread factory value. The remaining command args are
+     * scanned for unsupported options and are appended to the
+     * ProcessBuilder.
+     *
      * @param command Arguments to pass to the java command.
      * @return The ProcessBuilder instance representing the java command.
      */
@@ -566,14 +608,12 @@ public final class ProcessTools {
     }
 
     /**
-     * Executes a test jvm process, waits for it to finish and returns the process output.
-     * The default jvm options from jtreg, test.vm.opts and test.java.opts, are added.
-     * The java from the test.jdk is used to execute the command.
-     * <p>
-     * The command line will be like:
-     * {test.jdk}/bin/java {test.vm.opts} {test.java.opts} cmds
-     * <p>
-     * The jvm process will have exited before this method returns.
+     * Executes a test jvm process, waits for it to finish and returns
+     * the process output.
+     *
+     * <p>The process is created using runtime flags set up by:
+     * {@link #createTestJavaProcessBuilder(String...)}. The
+     * jvm process will have exited before this method returns.
      *
      * @param cmds User specified arguments.
      * @return The output from the process.
@@ -583,14 +623,12 @@ public final class ProcessTools {
     }
 
     /**
-     * Executes a test jvm process, waits for it to finish and returns the process output.
-     * The default jvm options from jtreg, test.vm.opts and test.java.opts, are added.
-     * The java from the test.jdk is used to execute the command.
-     * <p>
-     * The command line will be like:
-     * {test.jdk}/bin/java {test.vm.opts} {test.java.opts} cmds
-     * <p>
-     * The jvm process will have exited before this method returns.
+     * Executes a test jvm process, waits for it to finish and returns
+     * the process output.
+     *
+     * <p>The process is created using runtime flags set up by:
+     * {@link #createTestJavaProcessBuilder(String...)}. The
+     * jvm process will have exited before this method returns.
      *
      * @param cmds User specified arguments.
      * @return The output from the process.