ToolProvider (Java SE 10 & JDK 10 ) (original) (raw)

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

  All Methods Static Methods Instance Methods Abstract Methods Default Methods

  Modifier and Type	Method	Description
  static Optional<ToolProvider>	findFirst​(String name)	Returns the first instance of a ToolProvider with the given name, as loaded by ServiceLoader using the system class loader.
  String	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 Detail

     * #### name  
     [String](../../../java/lang/String.html "class in java.lang") 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  
     * #### run  
     int run​([PrintWriter](../../../java/io/PrintWriter.html "class in java.io") out,  
             [PrintWriter](../../../java/io/PrintWriter.html "class in java.io") err,  
             [String](../../../java/lang/String.html "class in java.lang")... args)  
     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 written  
     `err` \- a stream to which any error messages should be written  
     `args` \- 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](../../../java/lang/NullPointerException.html "class in java.lang")` \- if any of the arguments are `null`, or if there are any `null` values in the `args` array  
     * #### run  
     default int run​([PrintStream](../../../java/io/PrintStream.html "class in java.io") out,  
                     [PrintStream](../../../java/io/PrintStream.html "class in java.io") err,  
                     [String](../../../java/lang/String.html "class in java.lang")... args)  
     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` and `err` streams within [PrintWriter](../../../java/io/PrintWriter.html "class in java.io")s, and then calls[run(PrintWriter, PrintWriter, String\[\])](../../../java/util/spi/ToolProvider.html#run%28java.io.PrintWriter,java.io.PrintWriter,java.lang.String...%29).  
     Parameters:  
     `out` \- a stream to which "expected" output should be written  
     `err` \- a stream to which any error messages should be written  
     `args` \- 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](../../../java/lang/NullPointerException.html "class in java.lang")` \- if any of the arguments are `null`, or if there are any `null` values in the `args` array  
     * #### findFirst  
     static [Optional](../../../java/util/Optional.html "class in java.util")<[ToolProvider](../../../java/util/spi/ToolProvider.html "interface in java.util.spi")> findFirst​([String](../../../java/lang/String.html "class in java.lang") name)  
     Returns the first instance of a `ToolProvider` with the given name, as loaded by [ServiceLoader](../../../java/util/ServiceLoader.html "class in java.util") 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](../../../java/lang/NullPointerException.html "class in java.lang")` \- if `name` is `null`

Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2018, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.