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 } |