Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8286659

Add an optional description accessor on ToolProvider interface

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 19
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Adding a new default method in a rarely implemented and seldom used interface has a minimal risk leading to incompatible changes.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Add new default method description() to the java.util.spi.ToolProvider interface that returns a short one-line description of the provided tool, or an empty Optional if no description is available.

      Problem

      There is no way for an author of a tool implementation supplying a description of the tool's purpose that can be retrieved programmatically.

      Solution

      Adding an optional description accessor on the ToolProvider interface.

      Also, all tools in the JDK implementing the ToolProvider interface are updated to provide a short description of their purpose. This includes the jar, javac, javadoc, and jpackage tools.

      Implementions are encouraged to return a description using the default locale.

      As an alternative authors may override the toString() method in order to pass a description to users. This is not a good solution as users can not easily distinguish between a default and a custom string-represention.

      Specification

      /**
       * {@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();
      }

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              cstein Christian Stein
              Reporter:
              cstein Christian Stein
              Reviewed By:
              Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: