[commit-cp] classpath ChangeLog java/lang/ProcessBuilder.ja... [generics]

[Andrew John Hughes]

CVSROOT:        /cvsroot/classpath
Module name:    classpath
Branch:         generics
Changes by:     Andrew John Hughes <gnu_andrew> 06/06/03 16:02:08

Modified files:
        .              : ChangeLog 
        java/lang      : ProcessBuilder.java System.java 

Log message:
        2006-06-03  Andrew John Hughes  <address@hidden>
        
                * java/lang/ProcessBuilder.java:
                Documented.
                (environment): Create as a copy.
                * java/lang/System.java:
                (EnvironmentMap.EnvironmentMap(Map<String,String>)):
                New constructor.
                (EnvironmentMap.put(String,String)): Override superclass
                method with checks for nulls and non-Strings.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/classpath/ChangeLog?cvsroot=classpath&only_with_tag=generics&r1=1.2386.2.259&r2=1.2386.2.260
http://cvs.savannah.gnu.org/viewcvs/classpath/java/lang/ProcessBuilder.java?cvsroot=classpath&only_with_tag=generics&r1=1.1.2.3&r2=1.1.2.4
http://cvs.savannah.gnu.org/viewcvs/classpath/java/lang/System.java?cvsroot=classpath&only_with_tag=generics&r1=1.38.2.18&r2=1.38.2.19

Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/classpath/classpath/ChangeLog,v
retrieving revision 1.2386.2.259
retrieving revision 1.2386.2.260
diff -u -b -r1.2386.2.259 -r1.2386.2.260
--- ChangeLog   29 May 2006 16:19:43 -0000      1.2386.2.259
+++ ChangeLog   3 Jun 2006 16:02:04 -0000       1.2386.2.260
@@ -1,3 +1,14 @@
+2006-06-03  Andrew John Hughes  <address@hidden>
+
+       * java/lang/ProcessBuilder.java:
+       Documented.
+       (environment): Create as a copy.
+       * java/lang/System.java:
+       (EnvironmentMap.EnvironmentMap(Map<String,String>)):
+       New constructor.
+       (EnvironmentMap.put(String,String)): Override superclass
+       method with checks for nulls and non-Strings.
+       
 2006-05-29  Audrius Meskauskas  <address@hidden>
 
        * gnu/java/awt/peer/gtk/GdkGraphics2D.java (copying constructor):

Index: java/lang/ProcessBuilder.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/Attic/ProcessBuilder.java,v
retrieving revision 1.1.2.3
retrieving revision 1.1.2.4
diff -u -b -r1.1.2.3 -r1.1.2.4
--- java/lang/ProcessBuilder.java       26 Mar 2006 23:47:30 -0000      1.1.2.3
+++ java/lang/ProcessBuilder.java       3 Jun 2006 16:02:08 -0000       1.1.2.4
@@ -40,72 +40,293 @@
 
 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 (address@hidden Process#getOutputStream()}) and one for 
error data
+ * (address@hidden 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 address@hidden Process#getOutputStream()}, and the
+ * stream returned by address@hidden 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 (address@hidden)
+ * @author Andrew John Hughes (address@hidden)
+ * @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;
-  // FIXME: make a copy.
-  private Map<String, String> environment = System.getenv();
+
+  /**
+   * 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
+   * address@hidden 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 address@hidden 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!

Index: java/lang/System.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/System.java,v
retrieving revision 1.38.2.18
retrieving revision 1.38.2.19
diff -u -b -r1.38.2.18 -r1.38.2.19
--- java/lang/System.java       20 May 2006 22:55:04 -0000      1.38.2.18
+++ java/lang/System.java       3 Jun 2006 16:02:08 -0000       1.38.2.19
@@ -847,7 +847,7 @@
    *
    * @author Andrew John Hughes (address@hidden)
    */
-  private static class EnvironmentMap
+  static class EnvironmentMap
     extends HashMap<String,String>
   {
     
@@ -875,6 +875,19 @@
     }
     
     /**
+     * Constructs a new <code>EnvironmentMap</code> containing
+     * the contents of the specified map.
+     *
+     * @param m the map to be added to this.
+     * @throws NullPointerException if a key or value is null.
+     * @throws ClassCastException if a key or value is not a String.
+     */    
+    EnvironmentMap(Map<String,String> m)
+    {
+      super(m);
+    }
+
+    /**
      * Blocks queries containing a null key or one which is not
      * of type <code>String</code>.  All other queries
      * are forwarded to the superclass.
@@ -960,6 +973,31 @@
     }
     
     /**
+     * Associates the given key to the given value. If the
+     * map already contains the key, its value is replaced.
+     * The map does not accept null keys or values, or keys
+     * and values not of type address@hidden String}.
+     *
+     * @param key the key to map.
+     * @param value the value to be mapped.
+     * @return the previous value of the key, or null if there was no mapping
+     * @throws NullPointerException if a key or value is null.
+     * @throws ClassCastException if a key or value is not a String.
+     */
+    public String put(String key, String value)
+    {
+      if (key == null)
+       throw new NullPointerException("A new key is null.");
+      if (value == null)
+       throw new NullPointerException("A new value is null.");
+      if (!(key instanceof String))
+       throw new ClassCastException("A new key is not a String.");
+      if (!(value instanceof String))
+       throw new ClassCastException("A new value is not a String.");
+      return super.put(key, value);
+    }
+
+    /**
      * Removes a key-value pair from the map.  The queried key may not
      * be null or of a type other than a <code>String</code>.
      *