src/java.base/share/classes/java/util/spi/ToolProvider.java

*** 54,74 ****
   */
  public interface ToolProvider {
      /**
       * Returns the name of this tool provider.
       *
!      * @apiNote It is recommended that the name be the same as would be used on
!      *      the command line: for example, "javac", "jar", "jlink".
       *
       * @return the name of this tool provider
       */
      String name();
  
      /**
       * Runs an instance of the tool, returning zero for a successful run.
       * Any non-zero return value indicates a tool-specific error during the
       * execution.
       * Two streams should be provided, for "expected" output, and for any
       * error messages. If it is not necessary to distinguish the output,
       * the same stream may be used for both.
       *
       * @apiNote The interpretation of the arguments will be specific to
--- 54,75 ----
   */
  public interface ToolProvider {
      /**
       * Returns the name of this tool provider.
       *
!      * @apiNote It is recommended that the name be the same as would be
!      * used on the command line: for example, "javac", "jar", "jlink".
       *
       * @return the name of this tool provider
       */
      String name();
  
      /**
       * Runs an instance of the tool, returning zero for a successful run.
       * Any non-zero return value indicates a tool-specific error during the
       * execution.
+      *
       * Two streams should be provided, for "expected" output, and for any
       * error messages. If it is not necessary to distinguish the output,
       * the same stream may be used for both.
       *
       * @apiNote The interpretation of the arguments will be specific to
*** 80,125 ****
       *
       * @param args the command-line arguments for the tool
       *
       * @return the result of executing the tool.
       *      A return value of 0 means the tool did not encounter any errors;
!      *      any other value indicates that at least one error occurred during
!      *      execution.
       *
       * @throws NullPointerException if any of the arguments are {@code null},
!      *      or if there are any {@code null} values in the {@code args} array
       */
      int run(PrintWriter out, PrintWriter err, String... args);
  
      /**
       * Runs an instance of the tool, returning zero for a successful run.
       * Any non-zero return value indicates a tool-specific error during the
       * execution.
       * Two streams should be provided, for "expected" output, and for any
       * error messages. If it is not necessary to distinguish the output,
       * the same stream may be used for both.
       *
       * @apiNote The interpretation of the arguments will be specific to
       *      each tool.
       *
       * @implNote This implementation wraps the {@code out} and {@code err}
       *      streams within {@link PrintWriter}s, and then calls
!      *      {@link run(PrintWriter, PrintWriter, String[])}.
       *
       * @param out a stream to which "expected" output should be written
       *
       * @param err a stream to which any error messages should be written
       *
       * @param args the command-line arguments for the tool
       *
       * @return the result of executing the tool.
       *      A return value of 0 means the tool did not encounter any errors;
!      *      any other value indicates that at least one error occurred during
!      *      execution.
       *
       * @throws NullPointerException if any of the arguments are {@code null},
!      *      or if there are any {@code null} values in the {@code args} array
       */
      default int run(PrintStream out, PrintStream err, String... args) {
          Objects.requireNonNull(out);
          Objects.requireNonNull(err);
          for (String arg : args) {
--- 81,129 ----
       *
       * @param args the command-line arguments for the tool
       *
       * @return the result of executing the tool.
       *         A return value of 0 means the tool did not encounter any errors;
!      *         any other value indicates that at least one error occurred
!      *         during execution.
       *
       * @throws NullPointerException if any of the arguments are {@code null},
!      *         or if there are any {@code null} values in the {@code args}
!      *         array
       */
      int run(PrintWriter out, PrintWriter err, String... args);
  
      /**
       * Runs an instance of the tool, returning zero for a successful run.
       * Any non-zero return value indicates a tool-specific error during the
       * execution.
+      *
       * Two streams should be provided, for "expected" output, and for any
       * error messages. If it is not necessary to distinguish the output,
       * the same stream may be used for both.
       *
       * @apiNote The interpretation of the arguments will be specific to
       * each tool.
       *
       * @implNote This implementation wraps the {@code out} and {@code err}
       * streams within {@link PrintWriter}s, and then calls
!      * {@link #run(PrintWriter, PrintWriter, String[])}.
       *
       * @param out a stream to which "expected" output should be written
       *
       * @param err a stream to which any error messages should be written
       *
       * @param args the command-line arguments for the tool
       *
       * @return the result of executing the tool.
       *         A return value of 0 means the tool did not encounter any errors;
!      *         any other value indicates that at least one error occurred
!      *         during execution.
       *
       * @throws NullPointerException if any of the arguments are {@code null},
!      *         or if there are any {@code null} values in the {@code args}
!      *         array
       */
      default int run(PrintStream out, PrintStream err, String... args) {
          Objects.requireNonNull(out);
          Objects.requireNonNull(err);
          for (String arg : args) {