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 <[EMAIL PROTECTED]>
* 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 <[EMAIL PROTECTED]>
+
+ * 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 <[EMAIL PROTECTED]>
* 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 ([EMAIL PROTECTED] Process#getOutputStream()}) and one for
error data
+ * ([EMAIL PROTECTED] 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 [EMAIL PROTECTED] Process#getOutputStream()}, and the
+ * stream returned by [EMAIL PROTECTED] 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 ([EMAIL PROTECTED])
+ * @author Andrew John Hughes ([EMAIL PROTECTED])
+ * @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
+ * [EMAIL PROTECTED] 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 [EMAIL PROTECTED]
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 ([EMAIL PROTECTED])
*/
- 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 [EMAIL PROTECTED] 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>.
*
