001    /*
002     * Copyright 2005-2006 Sun Microsystems, Inc.  All Rights Reserved.
003     * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004     *
005     * This code is free software; you can redistribute it and/or modify it
006     * under the terms of the GNU General Public License version 2 only, as
007     * published by the Free Software Foundation.  Sun designates this
008     * particular file as subject to the "Classpath" exception as provided
009     * by Sun in the LICENSE file that accompanied this code.
010     *
011     * This code is distributed in the hope that it will be useful, but WITHOUT
012     * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013     * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014     * version 2 for more details (a copy is included in the LICENSE file that
015     * accompanied this code).
016     *
017     * You should have received a copy of the GNU General Public License version
018     * 2 along with this work; if not, write to the Free Software Foundation,
019     * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020     *
021     * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022     * CA 95054 USA or visit www.sun.com if you need additional information or
023     * have any questions.
024     */
025    
026    package javax.tools;
027    
028    import java.util.Set;
029    import java.io.InputStream;
030    import java.io.OutputStream;
031    import javax.lang.model.SourceVersion;
032    
033    /**
034     * Common interface for tools that can be invoked from a program.
035     * A tool is traditionally a command line program such as a compiler.
036     * The set of tools available with a platform is defined by the
037     * vendor.
038     *
039     * <p>Tools can be located using {@link
040     * java.util.ServiceLoader#load(Class)}.
041     *
042     * @author Neal M Gafter
043     * @author Peter von der Ah&eacute;
044     * @author Jonathan Gibbons
045     * @since 1.6
046     */
047    public interface Tool {
048    
049        /**
050         * Run the tool with the given I/O channels and arguments. By
051         * convention a tool returns 0 for success and nonzero for errors.
052         * Any diagnostics generated will be written to either {@code out}
053         * or {@code err} in some unspecified format.
054         *
055         * @param in "standard" input; use System.in if null
056         * @param out "standard" output; use System.out if null
057         * @param err "standard" error; use System.err if null
058         * @param arguments arguments to pass to the tool
059         * @return 0 for success; nonzero otherwise
060         * @throws NullPointerException if the array of arguments contains
061         * any {@code null} elements.
062         */
063        int run(InputStream in, OutputStream out, OutputStream err, String... arguments);
064    
065        /**
066         * Gets the source versions of the Java&trade; programming language
067         * supported by this tool.
068         * @return a set of supported source versions
069         */
070        Set<SourceVersion> getSourceVersions();
071    
072    }