< prev index next >

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

Print this page




  39  * be invoked without necessarily starting a new VM.
  40  *
  41  * <p>Tool providers are normally located using the service-provider
  42  * loading facility defined by {@link ServiceLoader}.
  43  * Each provider must provide a name, and a method to run
  44  * an instance of the corresponding tool. When a tool is run,
  45  * it will be provided with an array of string arguments, and a
  46  * pair of streams: one for normal (or expected) output and the other
  47  * for reporting any errors that may occur.
  48  * The interpretation of the string arguments will normally be defined by
  49  * each individual tool provider, but will generally correspond to the
  50  * arguments that could be provided to the tool when invoking the tool
  51  * from the command line.
  52  *
  53  * @since 9
  54  */
  55 public interface ToolProvider {
  56     /**
  57      * Returns the name of this tool provider.
  58      *
  59      * @apiNote It is recommended that the name be the same as would be used on
  60      *      the command line: for example, "javac", "jar", "jlink".
  61      *
  62      * @return the name of this tool provider
  63      */
  64     String name();
  65 
  66     /**
  67      * Runs an instance of the tool, returning zero for a successful run.
  68      * Any non-zero return value indicates a tool-specific error during the
  69      * execution.

  70      * Two streams should be provided, for "expected" output, and for any
  71      * error messages. If it is not necessary to distinguish the output,
  72      * the same stream may be used for both.
  73      *
  74      * @apiNote The interpretation of the arguments will be specific to
  75      *      each tool.
  76      *
  77      * @param out a stream to which "expected" output should be written
  78      *
  79      * @param err a stream to which any error messages should be written
  80      *
  81      * @param args the command-line arguments for the tool
  82      *
  83      * @return the result of executing the tool.
  84      *      A return value of 0 means the tool did not encounter any errors;
  85      *      any other value indicates that at least one error occurred during
  86      *      execution.
  87      *
  88      * @throws NullPointerException if any of the arguments are {@code null},
  89      *      or if there are any {@code null} values in the {@code args} array

  90      */
  91     int run(PrintWriter out, PrintWriter err, String... args);
  92 
  93     /**
  94      * Runs an instance of the tool, returning zero for a successful run.
  95      * Any non-zero return value indicates a tool-specific error during the
  96      * execution.

  97      * Two streams should be provided, for "expected" output, and for any
  98      * error messages. If it is not necessary to distinguish the output,
  99      * the same stream may be used for both.
 100      *
 101      * @apiNote The interpretation of the arguments will be specific to
 102      *      each tool.
 103      *
 104      * @implNote This implementation wraps the {@code out} and {@code err}
 105      *      streams within {@link PrintWriter}s, and then calls
 106      *      {@link run(PrintWriter, PrintWriter, String[])}.
 107      *
 108      * @param out a stream to which "expected" output should be written
 109      *
 110      * @param err a stream to which any error messages should be written
 111      *
 112      * @param args the command-line arguments for the tool
 113      *
 114      * @return the result of executing the tool.
 115      *      A return value of 0 means the tool did not encounter any errors;
 116      *      any other value indicates that at least one error occurred during
 117      *      execution.
 118      *
 119      * @throws NullPointerException if any of the arguments are {@code null},
 120      *      or if there are any {@code null} values in the {@code args} array

 121      */
 122     default int run(PrintStream out, PrintStream err, String... args) {
 123         Objects.requireNonNull(out);
 124         Objects.requireNonNull(err);
 125         for (String arg : args) {
 126             Objects.requireNonNull(args);
 127         }
 128 
 129         PrintWriter outWriter = new PrintWriter(out);
 130         PrintWriter errWriter = new PrintWriter(err);
 131         try {
 132             try {
 133                 return run(outWriter, errWriter, args);
 134             } finally {
 135                 outWriter.flush();
 136             }
 137         } finally {
 138             errWriter.flush();
 139         }
 140     }




  39  * be invoked without necessarily starting a new VM.
  40  *
  41  * <p>Tool providers are normally located using the service-provider
  42  * loading facility defined by {@link ServiceLoader}.
  43  * Each provider must provide a name, and a method to run
  44  * an instance of the corresponding tool. When a tool is run,
  45  * it will be provided with an array of string arguments, and a
  46  * pair of streams: one for normal (or expected) output and the other
  47  * for reporting any errors that may occur.
  48  * The interpretation of the string arguments will normally be defined by
  49  * each individual tool provider, but will generally correspond to the
  50  * arguments that could be provided to the tool when invoking the tool
  51  * from the command line.
  52  *
  53  * @since 9
  54  */
  55 public interface ToolProvider {
  56     /**
  57      * Returns the name of this tool provider.
  58      *
  59      * @apiNote It is recommended that the name be the same as would be
  60      * used on the command line: for example, "javac", "jar", "jlink".
  61      *
  62      * @return the name of this tool provider
  63      */
  64     String name();
  65 
  66     /**
  67      * Runs an instance of the tool, returning zero for a successful run.
  68      * Any non-zero return value indicates a tool-specific error during the
  69      * execution.
  70      *
  71      * Two streams should be provided, for "expected" output, and for any
  72      * error messages. If it is not necessary to distinguish the output,
  73      * the same stream may be used for both.
  74      *
  75      * @apiNote The interpretation of the arguments will be specific to
  76      * each tool.
  77      *
  78      * @param out a stream to which "expected" output should be written
  79      *
  80      * @param err a stream to which any error messages should be written
  81      *
  82      * @param args the command-line arguments for the tool
  83      *
  84      * @return the result of executing the tool.
  85      *         A return value of 0 means the tool did not encounter any errors;
  86      *         any other value indicates that at least one error occurred
  87      *         during execution.
  88      *
  89      * @throws NullPointerException if any of the arguments are {@code null},
  90      *         or if there are any {@code null} values in the {@code args}
  91      *         array
  92      */
  93     int run(PrintWriter out, PrintWriter err, String... args);
  94 
  95     /**
  96      * Runs an instance of the tool, returning zero for a successful run.
  97      * Any non-zero return value indicates a tool-specific error during the
  98      * execution.
  99      *
 100      * Two streams should be provided, for "expected" output, and for any
 101      * error messages. If it is not necessary to distinguish the output,
 102      * the same stream may be used for both.
 103      *
 104      * @apiNote The interpretation of the arguments will be specific to
 105      * each tool.
 106      *
 107      * @implNote This implementation wraps the {@code out} and {@code err}
 108      * streams within {@link PrintWriter}s, and then calls
 109      * {@link #run(PrintWriter, PrintWriter, String[])}.
 110      *
 111      * @param out a stream to which "expected" output should be written
 112      *
 113      * @param err a stream to which any error messages should be written
 114      *
 115      * @param args the command-line arguments for the tool
 116      *
 117      * @return the result of executing the tool.
 118      *         A return value of 0 means the tool did not encounter any errors;
 119      *         any other value indicates that at least one error occurred
 120      *         during execution.
 121      *
 122      * @throws NullPointerException if any of the arguments are {@code null},
 123      *         or if there are any {@code null} values in the {@code args}
 124      *         array
 125      */
 126     default int run(PrintStream out, PrintStream err, String... args) {
 127         Objects.requireNonNull(out);
 128         Objects.requireNonNull(err);
 129         for (String arg : args) {
 130             Objects.requireNonNull(args);
 131         }
 132 
 133         PrintWriter outWriter = new PrintWriter(out);
 134         PrintWriter errWriter = new PrintWriter(err);
 135         try {
 136             try {
 137                 return run(outWriter, errWriter, args);
 138             } finally {
 139                 outWriter.flush();
 140             }
 141         } finally {
 142             errWriter.flush();
 143         }
 144     }


< prev index next >