path: root/java/lang/ProcessBuilder.java

/* ProcessBuilder.java - Represent spawned system process
   Copyright (C) 2005  Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath 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 for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */


package java.lang;

import java.io.File;
import java.io.IOException;

import java.util.Arrays;
import java.util.List;
import java.util.Map;

/**
 * <p>
 * This class is used to construct new operating system processes.
 * A <code>ProcessBuilder</code> instance basically represent a
 * template for a new process.  Actual processes are generated from
 * this template via use of the <code>start()</code> method, which
 * may be invoked multiple times, with each invocation spawning a
 * new process with the current attributes of the
 * <code>ProcessBuilder</code> object.  Each spawned process is
 * independent of the <code>ProcessBuilder</code> object, and is
 * unaffected by changes in its attributes.
 * </p>
 * <p>
 * The following attributes define a process:
 * </p>
 * <ul>
 * <li>The <emphasis>working directory</emphasis>; the activities of a
 * process begin with the current directory set to this.  By default,
 * this is the working directory of the current process, as defined
 * by the <code>user.dir</code> property.</li>
 * <li>The <emphasis>command</emphasis> which invokes the process.  This
 * usually consists of the name of the program binary followed by an
 * arbitrary number of arguments.  For example, <code>find -type f</code>
 * invokes the <code>find</code> binary with the arguments "-type" and "f".
 * The command is provided a list, the elements of which are defined in a
 * system dependent manner; the layout is affected by expected operating
 * system conventions.  A common method is to split the command on each
 * space within the string.  Thus, <code>find -type f</code> forms a
 * three element list.  However, in some cases, the expectation is that
 * this split is performed by the program itself; thus, the list consists
 * of only two elements (the program name and its arguments).</li>
 * <li>The <emphasis>environment map</emphasis>, which links environment
 * variables to their corresponding values.  The initial contents of the map
 * are the current environment values i.e. it contains the contents of the
 * map returned by <code>System.getenv()</code>.</li>
 * <li>The <emphasis>redirection flag</emphasis>, which specifies whether
 * or not the contents of the error stream should be redirected to standard
 * output.  By default, this is false, and there are two output streams, one
 * for normal data ({@link Process#getOutputStream()}) and one for error data
 * ({@link Process#getErrorStream()}).  When set to true, the two are merged,
 * which simplifies the interleaving of the two streams.  Data is read using
 * the stream returned by {@link Process#getOutputStream()}, and the
 * stream returned by {@link Process#getErrorStream()} throws an immediate
 * end-of-file exception.</li>
 * </ul>
 * <p>
 * All checks on attribute validity are delayed until <code>start()</code>
 * is called. <code>ProcessBuilder</code> objects are <strong>not
 * synchronized</strong>; the user must provide external synchronization
 * where multiple threads may interact with the same
 * <code>ProcessBuilder</code> object.
 * </p>
 *
 * @author Tom Tromey (tromey@redhat.com)
 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
 * @see Process
 * @see System#getenv()
 * @since 1.5
 */
public final class ProcessBuilder
{

  /**
   * The working directory of the process.
   */
  private File directory = new File(System.getProperty("user.dir"));

  /**
   * The command line syntax for invoking the process.
   */
  private List<String> command;

  /**
   * The mapping of environment variables to values.
   */
  private Map<String, String> environment =
    new System.EnvironmentMap(System.getenv());

  /**
   * A flag indicating whether to redirect the error stream to standard
   * output.
   */
  private boolean redirect = false;

  /**
   * Constructs a new <code>ProcessBuilder</code> with the specified
   * command being used to invoke the process.  The list is used directly;
   * external changes are reflected in the <code>ProcessBuilder</code>.
   *
   * @param command the name of the program followed by its arguments.
   */
  public ProcessBuilder(List<String> command)
  {
    this.command = command;
  }

  /**
   * Constructs a new <code>ProcessBuilder</code> with the specified
   * command being used to invoke the process.  This constructor
   * simplifies creating a new <code>ProcessBuilder</code> by
   * converting the provided series of constructor arguments into a
   * list of command-line arguments.
   *
   * @param command the name of the program followed by its arguments.
   */
  public ProcessBuilder(String... command)
  {
    this.command = Arrays.asList(command);
  }

  /**
   * Returns the current command line, used to invoke the process.
   * The return value is simply a reference to the list of command
   * line arguments used by the <code>ProcessBuilder</code> object;
   * any changes made to it will be reflected in the operation of
   * the <code>ProcessBuilder</code>.
   *
   * @return the list of command-line arguments.
   */
  public List<String> command()
  {
    return command;
  }

  /**
   * Sets the command-line arguments to those specified.  The list is
   * used directly; external changes are reflected in the
   * <code>ProcessBuilder</code>.
   *
   * @param command the name of the program followed by its arguments.
   * @return a reference to this process builder.
   */
  public ProcessBuilder command(List<String> command)
  {
    this.command = command;
    return this;
  }

  /**
   * Sets the command-line arguments to those specified.
   * This simplifies modifying the arguments by converting
   * the provided series of constructor arguments into a
   * list of command-line arguments.
   *
   * @param command the name of the program followed by its arguments.
   * @return a reference to this process builder.
   */
  public ProcessBuilder command(String... command)
  {
    this.command = Arrays.asList(command);
    return this;
  }

  /**
   * Returns the working directory of the process.  The
   * returned value may be <code>null</code>; this
   * indicates that the default behaviour of using the
   * working directory of the current process should
   * be adopted.
   * 
   * @return the working directory.
   */
  public File directory()
  {
    return directory;
  }

  /**
   * Sets the working directory to that specified.
   * The supplied argument may be <code>null</code>,
   * which indicates the default value should be used.
   * The default is the working directory of the current
   * process.
   * 
   * @param directory the new working directory.
   * @return a reference to this process builder.
   */
  public ProcessBuilder directory(File directory)
  {
    this.directory = directory;
    return this;
  }

  /**
   * <p>
   * Returns the system environment variables of the process.
   * If the underlying system does not support environment variables,
   * an empty map is returned.
   * </p>
   * <p>
   * The returned map does not accept queries using
   * null keys or values, or those of a type other than
   * <code>String</code>.  Attempts to pass in a null value will
   * throw a <code>NullPointerException</code>.  Types other than
   * <code>String</code> throw a <code>ClassCastException</code>.
   * </p>
   * <p>
   * As the returned map is generated using data from the underlying
   * platform, it may not comply with the <code>equals()</code>
   * and <code>hashCode()</code> contracts.  It is also likely that
   * the keys of this map will be case-sensitive.
   * </p>
   * <p>
   * Modification of the map is reliant on the underlying platform;
   * some may not allow any changes to the environment variables or
   * may prevent certain values being used.  Attempts to do so will
   * throw an <code>UnsupportedOperationException</code> or
   * <code>IllegalArgumentException</code>, respectively. 
   * </p>
   * <p>
   * Use of this method may require a security check for the
   * RuntimePermission "getenv.*".
   * </p>
   *
   * @return a map of the system environment variables for the process.
   * @throws SecurityException if the checkPermission method of
   *         an installed security manager prevents access to
   *         the system environment variables.
   * @since 1.5
   */
  public Map<String, String> environment()
  {
    return environment;
  }

  /**
   * Returns true if the output stream and error stream of the
   * process will be merged to form one composite stream.  The
   * default return value is <code>false</code>.
   *
   * @return true if the output stream and error stream are to
   *         be merged.
   */
  public boolean redirectErrorStream()
  {
    return redirect;
  }

  /**
   * Sets the error stream redirection flag.  If set, the output
   * and error streams are merged to form one composite stream.
   *
   * @param redirect the new value of the redirection flag.
   * @return a reference to this process builder.
   */
  public ProcessBuilder redirectErrorStream(boolean redirect)
  {
    this.redirect = redirect;
    return this;
  }

  /**
   * <p>
   * Starts execution of a new process, based on the attributes of
   * this <code>ProcessBuilder</code> object.  This is the point
   * at which the command-line arguments are checked.  The list
   * must be non-empty and contain only non-null string objects.
   * The other attributes have default values which are used in
   * cases where their values are not explicitly specified.
   * </p>
   * <p>
   * If a security manager is in place, then the
   * {@link SecurityManager#checkExec()} method is called to
   * ensure that permission is given to execute the process.
   * </p>
   * <p>
   * The execution of the process is system-dependent.  Various
   * exceptions may result, due to problems at the operating system
   * level.  These are all returned as a form of {@link IOException}.
   * </p>
   *
   * @return a <code>Process</code> object, representing the spawned
   *         subprocess.
   * @throws IOException if a problem occurs with executing the process
   *                     at the operating system level.
   * @throws IndexOutOfBoundsException if the command to execute is
   *                                   actually an empty list.
   * @throws NullPointerException if the command to execute is null
   *                              or the list contains null elements.
   * @throws SecurityException if a security manager exists and prevents
   *                           execution of the subprocess.
   */
  public Process start() throws IOException
  {
    SecurityManager sm = SecurityManager.current; // Be thread-safe!
    if (sm != null)
      sm.checkExec(command.get(0));
    return VMProcess.exec(command, environment, directory, redirect);
  }
}