1 /* 2 * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.tools; 27 28 import java.util.Set; 29 import java.io.InputStream; 30 import java.io.OutputStream; 31 import javax.lang.model.SourceVersion; 32 33 /** 34 * Common interface for tools that can be invoked from a program. 35 * A tool is traditionally a command line program such as a compiler. 36 * The set of tools available with a platform is defined by the 37 * vendor. 38 * 39 * <p>Tools can be located using {@link 40 * java.util.ServiceLoader#load(Class)}. 41 * 42 * @author Neal M Gafter 43 * @author Peter von der Ahé 44 * @author Jonathan Gibbons 45 * @since 1.6 46 */ 47 public interface Tool { 48 /** 49 * Returns the name of this tool, or an empty string if no name is provided. 50 * 51 * @apiNote It is recommended that the name be the same as would be 52 * used on the command line: for example, "javac", "jar", "jlink". 53 * @implNote This implementation returns an empty string. 54 * 55 * @return the name of this tool 56 * @since 9 57 */ 58 default String name() { 59 return ""; 60 } 61 62 /** 63 * Run the tool with the given I/O channels and arguments. By 64 * convention a tool returns 0 for success and nonzero for errors. 65 * Any diagnostics generated will be written to either {@code out} 66 * or {@code err} in some unspecified format. 67 * 68 * @param in "standard" input; use System.in if null 69 * @param out "standard" output; use System.out if null 70 * @param err "standard" error; use System.err if null 71 * @param arguments arguments to pass to the tool 72 * @return 0 for success; nonzero otherwise 73 * @throws NullPointerException if the array of arguments contains 74 * any {@code null} elements. 75 */ 76 int run(InputStream in, OutputStream out, OutputStream err, String... arguments); 77 78 /** 79 * Returns the source versions of the Java programming language 80 * supported by this tool. 81 * @return a set of supported source versions 82 */ 83 Set<SourceVersion> getSourceVersions(); 84 85 }