8286654: Add an optional description accessor on ToolProvider interface

Reviewed-by: jjg, darcy, lancea

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -63,6 +63,30 @@ public interface ToolProvider {
      */
     String name();
 
+    /**
+     * {@return a short description of the tool, or an empty
+     * {@code Optional} if no description is available}
+     *
+     * @apiNote It is recommended that the description fits into a single
+     * line in order to allow creating concise overviews like the following:
+     * <pre>{@code
+     * jar
+     *   Create, manipulate, and extract an archive of classes and resources.
+     * javac
+     *   Read Java declarations and compile them into class files.
+     * jlink
+     *   Assemble a set of modules (...) into a custom runtime image.
+     * }
+     * </pre>
+     *
+     * @implSpec This implementation returns an empty {@code Optional}.
+     *
+     * @since 19
+     */
+    default Optional<String> description() {
+        return Optional.empty();
+    }
+
     /**
      * Runs an instance of the tool, returning zero for a successful run.
      * Any non-zero return value indicates a tool-specific error during the

src/jdk.compiler/share/classes/com/sun/tools/javac/main/JavacToolProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,8 +26,11 @@
 package com.sun.tools.javac.main;
 
 import java.io.PrintWriter;
+import java.util.Optional;
 import java.util.spi.ToolProvider;
 
+import com.sun.tools.javac.util.JavacMessages;
+
 /**
  * An implementation of the {@link java.util.spi.ToolProvider ToolProvider} SPI,
  * providing access to JDK Java compiler, javac.
@@ -41,6 +44,11 @@ public class JavacToolProvider implements ToolProvider {
         return "javac";
     }
 
+    public Optional<String> description() {
+        JavacMessages messages = new JavacMessages(Main.javacBundleName);
+        return Optional.of(messages.getLocalizedString("javac.description"));
+    }
+
     public int run(PrintWriter out, PrintWriter err, String... args) {
         Main compiler = new Main("javac", out, err);
         return compiler.compile(args).exitCode;

src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -23,6 +23,10 @@
 # questions.
 #
 
+## tool
+
+javac.description=read Java class and interface definitions and compile them into bytecode and class files
+
 ## standard options
 
 javac.opt.g=\

src/jdk.jartool/share/classes/sun/tools/jar/JarToolProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package sun.tools.jar;
 
 import java.io.PrintWriter;
+import java.util.Optional;
 import java.util.spi.ToolProvider;
 
 public class JarToolProvider implements ToolProvider {
@@ -33,6 +34,10 @@ public class JarToolProvider implements ToolProvider {
         return "jar";
     }
 
+    public Optional<String> description() {
+        return Optional.of(Main.getMsg("jar.description"));
+    }
+
     public int run(PrintWriter out, PrintWriter err, String... args) {
         boolean ok = new Main(out, err, name()).run(args);
         return ok ? 0 : 1;

src/jdk.jartool/share/classes/sun/tools/jar/resources/jar.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 1999, 2021, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -23,6 +23,10 @@
 # questions.
 #
 
+## tool
+
+jar.description=create an archive for classes and resources, and manipulate or restore individual classes or resources from an archive
+
 error.multiple.main.operations=\
      You may not specify more than one '-cuxtid' options
 error.cant.open=\

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocToolProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,7 +25,11 @@
 
 package jdk.javadoc.internal.tool;
 
+import com.sun.tools.javac.util.Context;
+import com.sun.tools.javac.util.JavacMessages;
 import java.io.PrintWriter;
+import java.util.Optional;
+import java.util.ResourceBundle;
 import java.util.spi.ToolProvider;
 
 /**
@@ -43,6 +47,13 @@ public class JavadocToolProvider implements ToolProvider {
         return "javadoc";
     }
 
+    // @Override - commented out due to interim builds of javadoc with JDKs < 19.
+    public Optional<String> description() {
+        JavacMessages messages = JavacMessages.instance(new Context());
+        messages.add(locale -> ResourceBundle.getBundle("jdk.javadoc.internal.tool.resources.javadoc", locale));
+        return Optional.of(messages.getLocalizedString("javadoc.description"));
+    }
+
     @Override
     public int run(PrintWriter out, PrintWriter err, String... args) {
         return Main.execute(args, out, err);

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/resources/javadoc.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -23,6 +23,8 @@
 # questions.
 #
 
+javadoc.description=generate HTML pages of API documentation from Java source files
+
 main.errors={0} errors
 main.error={0} error
 main.warnings={0} warnings

src/jdk.jdeps/share/classes/com/sun/tools/javap/Main.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2007, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package com.sun.tools.javap;
 
 import java.io.PrintWriter;
+import java.util.Optional;
 import java.util.spi.ToolProvider;
 
 /**
@@ -65,6 +66,11 @@ public class Main {
             return "javap";
         }
 
+        public Optional<String> description() {
+            JavapTask t = new JavapTask();
+            return Optional.of(t.getMessage("javap.description"));
+        }
+
         public int run(PrintWriter out, PrintWriter err, String... args) {
             return Main.run(args, out);
         }

src/jdk.jdeps/share/classes/com/sun/tools/javap/resources/javap.properties

@@ -23,6 +23,8 @@
 # questions.
 #
 
+javap.description=disassemble one or more class files
+
 err.prefix=Error:
 
 err.bad.constant.pool=error while reading constant pool for {0}: {1}

src/jdk.jdeps/share/classes/com/sun/tools/jdeps/Main.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package com.sun.tools.jdeps;
 
 import java.io.*;
+import java.util.Optional;
 import java.util.spi.ToolProvider;
 
 /**
@@ -69,6 +70,10 @@ public class Main {
             return "jdeps";
         }
 
+        public Optional<String> description() {
+            return Optional.of(JdepsTask.getMessage("jdeps.description"));
+        }
+
         public int run(PrintWriter out, PrintWriter err, String... args) {
             return Main.run(args, out);
         }

src/jdk.jdeps/share/classes/com/sun/tools/jdeps/resources/jdeps.properties

@@ -23,6 +23,8 @@
 # questions.
 #
 
+jdeps.description=launch the Java class dependency analyzer
+
 main.usage.summary=\
 Usage: {0} <options> <path ...>]\n\
 use --help for a list of possible options

src/jdk.jlink/share/classes/jdk/tools/jlink/internal/Main.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package jdk.tools.jlink.internal;
 
 import java.io.*;
+import java.util.Optional;
 import java.util.spi.ToolProvider;
 
 public class Main {
@@ -61,6 +62,12 @@ public class Main {
             return "jlink";
         }
 
+        @Override
+        public Optional<String> description() {
+            TaskHelper taskHelper = new TaskHelper(TaskHelper.JLINK_BUNDLE);
+            return Optional.of(taskHelper.getMessage("jlink.desciption"));
+        }
+
         @Override
         public int run(PrintWriter out, PrintWriter err, String... args) {
             return Main.run(out, err, args);

src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -23,6 +23,8 @@
 # questions.
 #
 
+jlink.description=assemble and optimize a set of modules and their dependencies into a custom runtime image
+
 main.usage.summary=\
 Usage: {0} <options> --module-path <modulepath> --add-modules <module>[,<module>...]\n\
 \Use --help for a list of possible options

src/jdk.jlink/share/classes/jdk/tools/jmod/JmodTask.java

@@ -1601,7 +1601,7 @@ public class JmodTask {
         return System.getProperty("java.version");
     }
 
-    private static String getMessage(String key, Object... args) {
+    static String getMessage(String key, Object... args) {
         try {
             return MessageFormat.format(ResourceBundleHelper.bundle.getString(key), args);
         } catch (MissingResourceException e) {

src/jdk.jlink/share/classes/jdk/tools/jmod/Main.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package jdk.tools.jmod;
 
 import java.io.*;
+import java.util.Optional;
 import java.util.spi.ToolProvider;
 
 public class Main {
@@ -55,6 +56,11 @@ public class Main {
             return "jmod";
         }
 
+        @Override
+        public Optional<String> description() {
+            return Optional.of(JmodTask.getMessage("jmod.description"));
+        }
+
         @Override
         public int run(PrintWriter out, PrintWriter err, String... args) {
             return Main.run(out, err, args);

src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod.properties

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -23,6 +23,8 @@
 # questions.
 #
 
+jmod.description=create JMOD files and list the content of existing JMOD files
+
 main.usage.summary=\
 Usage: {0} (create|extract|list|describe|hash) <OPTIONS> <jmod-file>\n\
 use --help for a list of possible options
@@ -115,5 +117,3 @@ warn.invalid.arg=Invalid classname or pathname not exist: {0}
 warn.no.module.hashes=No hashes recorded: no module specified for hashing depends on {0}
 warn.ignore.entry=ignoring entry {0}, in section {1}
 warn.ignore.duplicate.entry=ignoring duplicate entry {0}, in section {1}
-
-

src/jdk.jpackage/share/classes/jdk/jpackage/internal/JPackageToolProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,6 +26,7 @@
 package jdk.jpackage.internal;
 
 import java.io.PrintWriter;
+import java.util.Optional;
 import java.util.spi.ToolProvider;
 
 /**
@@ -40,6 +41,10 @@ public class JPackageToolProvider implements ToolProvider {
         return "jpackage";
     }
 
+    public Optional<String> description() {
+        return Optional.of(jdk.jpackage.main.Main.I18N.getString("jpackage.description"));
+    }
+
     public synchronized int run(
             PrintWriter out, PrintWriter err, String... args) {
         try {

src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/MainResources.properties

@@ -24,6 +24,8 @@
 #
 #
 
+jpackage.description=package a self-contained Java application
+
 param.copyright.default=Copyright (C) {0,date,YYYY}
 param.description.default=None
 param.vendor.default=Unknown

src/jdk.jpackage/share/classes/jdk/jpackage/main/Main.java

@@ -36,7 +36,7 @@ import java.text.MessageFormat;
 
 public class Main {
 
-    private static final ResourceBundle I18N = ResourceBundle.getBundle(
+    public static final ResourceBundle I18N = ResourceBundle.getBundle(
             "jdk.jpackage.internal.resources.MainResources");
 
     /**