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