/*

 * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.lang;

import java.io.File;

import java.io.FileDescriptor;

import java.io.IOException;

import java.io.InputStream;

import java.io.OutputStream;

import java.util.Arrays;

import java.util.ArrayList;

import java.util.List;

import java.util.Map;

import sun.security.action.GetPropertyAction;

/**

 * This class is used to create operating system processes.

 *

 * <p>Each {@code ProcessBuilder} instance manages a collection

 * of process attributes.  The {@link #start()} method creates a new

 * {@link Process} instance with those attributes.  The {@link

 * #start()} method can be invoked repeatedly from the same instance

 * to create new subprocesses with identical or related attributes.

 * <p>

 * The {@link #startPipeline startPipeline} method can be invoked to create

 * a pipeline of new processes that send the output of each process

 * directly to the next process.  Each process has the attributes of

 * its respective ProcessBuilder.

 *

 * <p>Each process builder manages these process attributes:

 *

 * <ul>

 *

 * <li>a <i>command</i>, a list of strings which signifies the

 * external program file to be invoked and its arguments, if any.

 * Which string lists represent a valid operating system command is

 * system-dependent.  For example, it is common for each conceptual

 * argument to be an element in this list, but there are operating

 * systems where programs are expected to tokenize command line

 * strings themselves - on such a system a Java implementation might

 * require commands to contain exactly two elements.

 *

 * <li>an <i>environment</i>, which is a system-dependent mapping from

 * <i>variables</i> to <i>values</i>.  The initial value is a copy of

 * the environment of the current process (see {@link System#getenv()}).

 *

 * <li>a <i>working directory</i>.  The default value is the current

 * working directory of the current process, usually the directory

 * named by the system property {@code user.dir}.

 *

 * <li><a name="redirect-input">a source of <i>standard input</i></a>.

 * By default, the subprocess reads input from a pipe.  Java code

 * can access this pipe via the output stream returned by

 * {@link Process#getOutputStream()}.  However, standard input may

 * be redirected to another source using

 * {@link #redirectInput(Redirect) redirectInput}.

 * In this case, {@link Process#getOutputStream()} will return a

 * <i>null output stream</i>, for which:

 *

 * <ul>

 * <li>the {@link OutputStream#write(int) write} methods always

 * throw {@code IOException}

 * <li>the {@link OutputStream#close() close} method does nothing

 * </ul>

 *

 * <li><a name="redirect-output">a destination for <i>standard output</i>

 * and <i>standard error</i></a>.  By default, the subprocess writes standard

 * output and standard error to pipes.  Java code can access these pipes

 * via the input streams returned by {@link Process#getOutputStream()} and

 * {@link Process#getErrorStream()}.  However, standard output and

 * standard error may be redirected to other destinations using

 * {@link #redirectOutput(Redirect) redirectOutput} and

 * {@link #redirectError(Redirect) redirectError}.

 * In this case, {@link Process#getInputStream()} and/or

 * {@link Process#getErrorStream()} will return a <i>null input

 * stream</i>, for which:

 *

 * <ul>

 * <li>the {@link InputStream#read() read} methods always return

 * {@code -1}

 * <li>the {@link InputStream#available() available} method always returns

 * {@code 0}

 * <li>the {@link InputStream#close() close} method does nothing

 * </ul>

 *

 * <li>a <i>redirectErrorStream</i> property.  Initially, this property

 * is {@code false}, meaning that the standard output and error

 * output of a subprocess are sent to two separate streams, which can

 * be accessed using the {@link Process#getInputStream()} and {@link

 * Process#getErrorStream()} methods.

 *

 * <p>If the value is set to {@code true}, then:

 *

 * <ul>

 * <li>standard error is merged with the standard output and always sent

 * to the same destination (this makes it easier to correlate error

 * messages with the corresponding output)

 * <li>the common destination of standard error and standard output can be

 * redirected using

 * {@link #redirectOutput(Redirect) redirectOutput}

 * <li>any redirection set by the

 * {@link #redirectError(Redirect) redirectError}

 * method is ignored when creating a subprocess

 * <li>the stream returned from {@link Process#getErrorStream()} will

 * always be a <a href="#redirect-output">null input stream</a>

 * </ul>

 *

 * </ul>

 *

 * <p>Modifying a process builder's attributes will affect processes

 * subsequently started by that object's {@link #start()} method, but

 * will never affect previously started processes or the Java process

 * itself.

 *

 * <p>Most error checking is performed by the {@link #start()} method.

 * It is possible to modify the state of an object so that {@link

 * #start()} will fail.  For example, setting the command attribute to

 * an empty list will not throw an exception unless {@link #start()}

 * is invoked.

 *

 * <p><strong>Note that this class is not synchronized.</strong>

 * If multiple threads access a {@code ProcessBuilder} instance

 * concurrently, and at least one of the threads modifies one of the

 * attributes structurally, it <i>must</i> be synchronized externally.

 *

 * <p>Starting a new process which uses the default working directory

 * and environment is easy:

 *

 * <pre> {@code

 * Process p = new ProcessBuilder("myCommand", "myArg").start();

 * }</pre>

 *

 * <p>Here is an example that starts a process with a modified working

 * directory and environment, and redirects standard output and error

 * to be appended to a log file:

 *

 * <pre> {@code

 * ProcessBuilder pb =

 *   new ProcessBuilder("myCommand", "myArg1", "myArg2");

 * Map<String, String> env = pb.environment();

 * env.put("VAR1", "myValue");

 * env.remove("OTHERVAR");

 * env.put("VAR2", env.get("VAR1") + "suffix");

 * pb.directory(new File("myDir"));

 * File log = new File("log");

 * pb.redirectErrorStream(true);

 * pb.redirectOutput(Redirect.appendTo(log));

 * Process p = pb.start();

 * assert pb.redirectInput() == Redirect.PIPE;

 * assert pb.redirectOutput().file() == log;

 * assert p.getInputStream().read() == -1;

 * }</pre>

 *

 * <p>To start a process with an explicit set of environment

 * variables, first call {@link java.util.Map#clear() Map.clear()}

 * before adding environment variables.

 *

 * <p>

 * Unless otherwise noted, passing a {@code null} argument to a constructor

 * or method in this class will cause a {@link NullPointerException} to be

 * thrown.

 *

 * @author Martin Buchholz

 * @since 1.5

 */

public final class ProcessBuilder

{

    private List<String> command;

    private File directory;

    private Map<String,String> environment;

    private boolean redirectErrorStream;

    private Redirect[] redirects;

    /**

     * Constructs a process builder with the specified operating

     * system program and arguments.  This constructor does <i>not</i>

     * make a copy of the {@code command} list.  Subsequent

     * updates to the list will be reflected in the state of the

     * process builder.  It is not checked whether

     * {@code command} corresponds to a valid operating system

     * command.

     *

     * @param  command the list containing the program and its arguments

     */

    public ProcessBuilder(List<String> command) {

        if (command == null)

            throw new NullPointerException();

        this.command = command;

    }

    /**

     * Constructs a process builder with the specified operating

     * system program and arguments.  This is a convenience

     * constructor that sets the process builder's command to a string

     * list containing the same strings as the {@code command}

     * array, in the same order.  It is not checked whether

     * {@code command} corresponds to a valid operating system

     * command.

     *

     * @param command a string array containing the program and its arguments

     */

    public ProcessBuilder(String... command) {

        this.command = new ArrayList<>(command.length);

        for (String arg : command)

            this.command.add(arg);

    }

    /**

     * Sets this process builder's operating system program and

     * arguments.  This method does <i>not</i> make a copy of the

     * {@code command} list.  Subsequent updates to the list will

     * be reflected in the state of the process builder.  It is not

     * checked whether {@code command} corresponds to a valid

     * operating system command.

     *

     * @param  command the list containing the program and its arguments

     * @return this process builder

     */

    public ProcessBuilder command(List<String> command) {

        if (command == null)

            throw new NullPointerException();

        this.command = command;

        return this;

    }

    /**

     * Sets this process builder's operating system program and

     * arguments.  This is a convenience method that sets the command

     * to a string list containing the same strings as the

     * {@code command} array, in the same order.  It is not

     * checked whether {@code command} corresponds to a valid

     * operating system command.

     *

     * @param  command a string array containing the program and its arguments

     * @return this process builder

     */

    public ProcessBuilder command(String... command) {

        this.command = new ArrayList<>(command.length);

        for (String arg : command)

            this.command.add(arg);

        return this;

    }

    /**

     * Returns this process builder's operating system program and

     * arguments.  The returned list is <i>not</i> a copy.  Subsequent

     * updates to the list will be reflected in the state of this

     * process builder.

     *

     * @return this process builder's program and its arguments

     */

    public List<String> command() {

        return command;

    }

    /**

     * Returns a string map view of this process builder's environment.

     *

     * Whenever a process builder is created, the environment is

     * initialized to a copy of the current process environment (see

     * {@link System#getenv()}).  Subprocesses subsequently started by

     * this object's {@link #start()} method will use this map as

     * their environment.

     *

     * <p>The returned object may be modified using ordinary {@link

     * java.util.Map Map} operations.  These modifications will be

     * visible to subprocesses started via the {@link #start()}

     * method.  Two {@code ProcessBuilder} instances always

     * contain independent process environments, so changes to the

     * returned map will never be reflected in any other

     * {@code ProcessBuilder} instance or the values returned by

     * {@link System#getenv System.getenv}.

     *

     * <p>If the system does not support environment variables, an

     * empty map is returned.

     *

     * <p>The returned map does not permit null keys or values.

     * Attempting to insert or query the presence of a null key or

     * value will throw a {@link NullPointerException}.

     * Attempting to query the presence of a key or value which is not

     * of type {@link String} will throw a {@link ClassCastException}.

     *

     * <p>The behavior of the returned map is system-dependent.  A

     * system may not allow modifications to environment variables or

     * may forbid certain variable names or values.  For this reason,

     * attempts to modify the map may fail with

     * {@link UnsupportedOperationException} or

     * {@link IllegalArgumentException}

     * if the modification is not permitted by the operating system.

     *

     * <p>Since the external format of environment variable names and

     * values is system-dependent, there may not be a one-to-one

     * mapping between them and Java's Unicode strings.  Nevertheless,

     * the map is implemented in such a way that environment variables

     * which are not modified by Java code will have an unmodified

     * native representation in the subprocess.

     *

     * <p>The returned map and its collection views may not obey the

     * general contract of the {@link Object#equals} and

     * {@link Object#hashCode} methods.

     *

     * <p>The returned map is typically case-sensitive on all platforms.

     *

     * <p>If a security manager exists, its

     * {@link SecurityManager#checkPermission checkPermission} method

     * is called with a

     * {@link RuntimePermission}{@code ("getenv.*")} permission.

     * This may result in a {@link SecurityException} being thrown.

     *

     * <p>When passing information to a Java subprocess,

     * <a href=System.html#EnvironmentVSSystemProperties>system properties</a>

     * are generally preferred over environment variables.

     *

     * @return this process builder's environment

     *

     * @throws SecurityException

     *         if a security manager exists and its

     *         {@link SecurityManager#checkPermission checkPermission}

     *         method doesn't allow access to the process environment

     *

     * @see    Runtime#exec(String[],String[],java.io.File)

     * @see    System#getenv()

     */

    public Map<String,String> environment() {

        SecurityManager security = System.getSecurityManager();

        if (security != null)

            security.checkPermission(new RuntimePermission("getenv.*"));

        if (environment == null)

            environment = ProcessEnvironment.environment();

        assert environment != null;

        return environment;

    }

    // Only for use by Runtime.exec(...envp...)

    ProcessBuilder environment(String[] envp) {

        assert environment == null;

        if (envp != null) {

            environment = ProcessEnvironment.emptyEnvironment(envp.length);

            assert environment != null;

            for (String envstring : envp) {

                // Before 1.5, we blindly passed invalid envstrings

                // to the child process.

                // We would like to throw an exception, but do not,

                // for compatibility with old broken code.

                // Silently discard any trailing junk.

                if (envstring.indexOf((int) '\u0000') != -1)

                    envstring = envstring.replaceFirst("\u0000.*", "");

                int eqlsign =

                    envstring.indexOf('=', ProcessEnvironment.MIN_NAME_LENGTH);

                // Silently ignore envstrings lacking the required `='.

                if (eqlsign != -1)

                    environment.put(envstring.substring(0,eqlsign),

                                    envstring.substring(eqlsign+1));

            }

        }

        return this;

    }

    /**

     * Returns this process builder's working directory.

     *

     * Subprocesses subsequently started by this object's {@link

     * #start()} method will use this as their working directory.

     * The returned value may be {@code null} -- this means to use

     * the working directory of the current Java process, usually the

     * directory named by the system property {@code user.dir},

     * as the working directory of the child process.

     *

     * @return this process builder's working directory

     */

    public File directory() {

        return directory;

    }

    /**

     * Sets this process builder's working directory.

     *

     * Subprocesses subsequently started by this object's {@link

     * #start()} method will use this as their working directory.

     * The argument may be {@code null} -- this means to use the

     * working directory of the current Java process, usually the

     * directory named by the system property {@code user.dir},

     * as the working directory of the child process.

     *

     * @param  directory the new working directory

     * @return this process builder

     */

    public ProcessBuilder directory(File directory) {

        this.directory = directory;

        return this;

    }

    // ---------------- I/O Redirection ----------------

    /**

     * Implements a <a href="#redirect-output">null input stream</a>.

     */

    static class NullInputStream extends InputStream {

        static final NullInputStream INSTANCE = new NullInputStream();

        private NullInputStream() {}

        public int read()      { return -1; }

        public int available() { return 0; }

    }

    /**

     * Implements a <a href="#redirect-input">null output stream</a>.

     */

    static class NullOutputStream extends OutputStream {

        static final NullOutputStream INSTANCE = new NullOutputStream();

        private NullOutputStream() {}

        public void write(int b) throws IOException {

            throw new IOException("Stream closed");

        }

    }

    /**

     * Represents a source of subprocess input or a destination of

     * subprocess output.

     *

     * Each {@code Redirect} instance is one of the following:

     *

     * <ul>

     * <li>the special value {@link #PIPE Redirect.PIPE}

     * <li>the special value {@link #INHERIT Redirect.INHERIT}

     * <li>the special value {@link #DISCARD Redirect.DISCARD}

     * <li>a redirection to read from a file, created by an invocation of

     *     {@link Redirect#from Redirect.from(File)}

     * <li>a redirection to write to a file,  created by an invocation of

     *     {@link Redirect#to Redirect.to(File)}

     * <li>a redirection to append to a file, created by an invocation of

     *     {@link Redirect#appendTo Redirect.appendTo(File)}

     * </ul>

     *

     * <p>Each of the above categories has an associated unique

     * {@link Type Type}.

     *

     * @since 1.7

     */

    public abstract static class Redirect {

        private static final File NULL_FILE = new File(

                (GetPropertyAction.privilegedGetProperty("os.name")

                        .startsWith("Windows") ? "NUL" : "/dev/null")

        );

        /**

         * The type of a {@link Redirect}.

         */

        public enum Type {

            /**

             * The type of {@link Redirect#PIPE Redirect.PIPE}.

             */

            PIPE,

            /**

             * The type of {@link Redirect#INHERIT Redirect.INHERIT}.

             */

            INHERIT,

            /**

             * The type of redirects returned from

             * {@link Redirect#from Redirect.from(File)}.

             */

            READ,

            /**

             * The type of redirects returned from

             * {@link Redirect#to Redirect.to(File)}.

             */

            WRITE,

            /**

             * The type of redirects returned from

             * {@link Redirect#appendTo Redirect.appendTo(File)}.

             */

            APPEND

        };