Interface ToolProvider
public interface ToolProvider
An interface for command-line tools to provide a way to
be invoked without necessarily starting a new VM.
Tool providers are normally located using the service-provider
loading facility defined by ServiceLoader
.
Each provider must provide a name, and a method to run
an instance of the corresponding tool. When a tool is run,
it will be provided with an array of string arguments, and a
pair of streams: one for normal (or expected) output and the other
for reporting any errors that may occur.
The interpretation of the string arguments will normally be defined by
each individual tool provider, but will generally correspond to the
arguments that could be provided to the tool when invoking the tool
from the command line.
- Since:
- 9
-
Method Summary
Modifier and TypeMethodDescriptionReturns a short description of the tool, or an emptyOptional
if no description is available.static Optional
<ToolProvider> Returns the first instance of aToolProvider
with the given name, as loaded byServiceLoader
using the system class loader.name()
Returns the name of this tool provider.default int
run
(PrintStream out, PrintStream err, String... args) Runs an instance of the tool, returning zero for a successful run.int
run
(PrintWriter out, PrintWriter err, String... args) Runs an instance of the tool, returning zero for a successful run.
-
Method Details
-
name
String name()Returns the name of this tool provider.- API Note:
- It is recommended that the name be the same as would be used on the command line: for example, "javac", "jar", "jlink".
- Returns:
- the name of this tool provider
-
description
Returns a short description of the tool, or an emptyOptional
if no description is available.- API Note:
- It is recommended that the description fits into a single
line in order to allow creating concise overviews like the following:
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.
- Implementation Requirements:
- This implementation returns an empty
Optional
. - Returns:
- a short description of the tool, or an empty
Optional
if no description is available - Since:
- 19
-
run
Runs an instance of the tool, returning zero for a successful run. Any non-zero return value indicates a tool-specific error during the execution. Two streams should be provided, for "expected" output, and for any error messages. If it is not necessary to distinguish the output, the same stream may be used for both.- API Note:
- The interpretation of the arguments will be specific to each tool.
- Parameters:
out
- a stream to which "expected" output should be writtenerr
- a stream to which any error messages should be writtenargs
- the command-line arguments for the tool- Returns:
- the result of executing the tool. A return value of 0 means the tool did not encounter any errors; any other value indicates that at least one error occurred during execution.
- Throws:
NullPointerException
- if any of the arguments arenull
, or if there are anynull
values in theargs
array
-
run
Runs an instance of the tool, returning zero for a successful run. Any non-zero return value indicates a tool-specific error during the execution. Two streams should be provided, for "expected" output, and for any error messages. If it is not necessary to distinguish the output, the same stream may be used for both.- API Note:
- The interpretation of the arguments will be specific to each tool.
- Implementation Note:
- This implementation wraps the
out
anderr
streams withinPrintWriter
s, and then callsrun(PrintWriter, PrintWriter, String[])
. - Parameters:
out
- a stream to which "expected" output should be writtenerr
- a stream to which any error messages should be writtenargs
- the command-line arguments for the tool- Returns:
- the result of executing the tool. A return value of 0 means the tool did not encounter any errors; any other value indicates that at least one error occurred during execution.
- Throws:
NullPointerException
- if any of the arguments arenull
, or if there are anynull
values in theargs
array
-
findFirst
Returns the first instance of aToolProvider
with the given name, as loaded byServiceLoader
using the system class loader.- Parameters:
name
- the name of the desired tool provider- Returns:
- an
Optional<ToolProvider>
of the first instance found - Throws:
NullPointerException
- ifname
isnull
-